decouplio 1.0.0alpha1 → 1.0.0alpha2

data/docs/doby_deny.md

@@ -0,0 +1,171 @@
+# Doby/Deny
+
+It's a step type to make configurable manipulations with action context.
+
+
+## Signature
+
+```ruby
+doby(class_constant, **options)
+deny(class_constant, **options)
+```
+
+## Behavior
+
+### Doby
+
+- `doby` behaves similar to `step`, depending on `.call` method returning value(truthy or falsy) the execution will be moved to `success or failure` track accordingly.
+- `doby` doesn't have `on_success, on_failure, if, unless, finish_him` options.
+- All options passed after class constant will be passed as kwargs for `.call` method.
+
+### Deny
+- `deny` behaves similar to `fail`, no matter which value will be returned by `.call` method, it moves to `failure` track.
+- `deny` doesn't have `on_success, on_failure, if, unless, finish_him` options.
+- All options passed after class constant will be passed as kwargs for `.call` method.
+
+
+## How to use?
+
+Create the ruby class which has `.call` class method.
+
+`.call` method signature:
+```ruby
+# :ctx - it's a ctx from Decouplio::Action
+# :error_store - it's an error_store from Decouplio::Action
+#                you can call #add_error method on it.
+# ** - kwargs passed from action.
+def self.call(ctx:, error_store:, **)
+end
+```
+
+```ruby
+class AssignDoby
+  def self.call(ctx:, to:, from: nil, value: nil, **)
+    raise 'from/value is empty' unless from || value
+
+    ctx[to] = value || ctx[from]
+  end
+end
+
+# OR
+
+class SemanticDeny
+  def self.call(ctx:, error_store:, semantic:, error_message:)
+    ctx[:semantic] = semantic
+    error_store.add_error(semantic, error_message)
+  end
+end
+
+# OR
+
+# If you don't need ctx and error_store, you can omit them
+class DummyDoby
+  def self.call(dummy:, **)
+    puts dummy
+  end
+end
+```
+
+`AssignDoby` example.
+```ruby
+require 'decouplio'
+
+class AssignDoby
+  def self.call(ctx:, to:, from: nil, value: nil, **)
+    raise 'from/value is empty' unless from || value
+
+    ctx[to] = value || ctx[from]
+  end
+end
+
+class SomeAction < Decouplio::Action
+  logic do
+    step :user
+    step AssignDoby, to: :current_user, from: :user
+  end
+
+  def user(id:, **)
+    ctx[:user] = "User with id: #{id}"
+  end
+end
+
+action = SomeAction.call(id: 1)
+
+action[:user] # => "User with id: 1"
+
+action[:current_user] # => "User with id: 1"
+
+action # =>
+# Result: success
+
+# Railway Flow:
+#   user -> AssignDoby
+
+# Context:
+#   {:id=>1, :user=>"User with id: 1", :current_user=>"User with id: 1"}
+
+# Errors:
+#   {}
+```
+`SemanticDeny` example.
+```ruby
+require 'decouplio'
+
+class SemanticDeny
+  def self.call(ctx:, error_store:, semantic:, error_message:)
+    ctx[:semantic] = semantic
+    error_store.add_error(semantic, error_message)
+  end
+end
+
+class SomeAction < Decouplio::Action
+  logic do
+    step :step_one
+    deny SemanticDeny, semantic: :bad_request, error_message: 'Bad request'
+    step :step_two
+  end
+
+  def step_one(step_one_param:, **)
+    ctx[:step_one] = step_one_param
+  end
+
+  def step_two(**)
+    ctx[:step_two] = 'Success'
+  end
+
+  def fail_one(**)
+    ctx[:fail_one] = 'Failure'
+  end
+end
+
+success_action = SomeAction.call(step_one_param: true)
+failure_action = SomeAction.call(step_one_param: false)
+
+success_action # =>
+# Result: success
+
+# Railway Flow:
+#   step_one -> step_two
+
+# Context:
+#   :step_one_param => true
+#   :step_one => true
+#   :step_two => "Success"
+
+# Errors:
+#   None
+
+failure_action # =>
+# Result: failure
+
+# Railway Flow:
+#   step_one -> SemanticDeny
+
+# Context:
+#   :step_one_param => false
+#   :step_one => false
+#   :semantic => :bad_request
+
+# Errors:
+#   :bad_request => ["Bad request"]
+```

data/docs/fail.md

@@ -88,6 +88,8 @@ fail(step_name, **options)
 |-|-|
 |:finish_him|action stops execution if `fail` method returns truthy value|
 |symbol with next step name|step with specified symbol name performs if step method returns truthy value|
+|:PASS|will direct execution flow to nearest success track step. If current step is the last step when action will finish as `success`|
+|:FAIL|will direct execution flow to nearest failure track step. If current step is the last step when action will finish as `failure`|
 
 ### on_success: :finish_him
 
@@ -387,11 +389,83 @@ fail(step_name, **options)
 
 ***
 
+### on_success: :PASS
+<details><summary><b>EXAMPLE (CLICK ME)</b></summary>
+<p>
+
+  ```ruby
+    require 'decouplio'
+    class SomeActionOnSuccessPass < Decouplio::Action
+      logic do
+        step :step_one
+        fail :fail_one, on_success: :PASS
+      end
+
+      def step_one(**)
+        ctx[:step_one] = false
+      end
+
+      def fail_one(fail_one_param:, **)
+        ctx[:fail_one] = fail_one_param
+      end
+    end
+
+    fail_step_success = SomeActionOnSuccessPass.call(fail_one_param: true)
+    fail_step_failure = SomeActionOnSuccessPass.call(fail_one_param: false)
+
+    fail_step_success # =>
+    # Result: success
+
+    # Railway Flow:
+    #   step_one -> fail_one
+
+    # Context:
+    #   :fail_one_param => true
+    #   :step_one => false
+    #   :fail_one => true
+
+    # Errors:
+    #   {}
+
+    fail_step_failure # =>
+    # Result: failure
+
+    # Railway Flow:
+    #   step_one -> fail_one
+
+    # Context:
+    #   :fail_one_param => false
+    #   :step_one => false
+    #   :fail_one => false
+
+    # Errors:
+    #   {}
+  ```
+
+  ```mermaid
+  flowchart LR
+      1(start)-->2(step_one);
+      2(step_one)-->|failure track|3(fail_one);
+      3(fail_one)-->|on_success: :PASS|5(finish_success);
+      3(fail_one)-->|failure track|4(finish_failure);
+  ```
+</p>
+</details>
+
+***
+
+### on_success: :FAIL
+It will perform like regular `fail` step, just move to next failure track step.
+
+***
+
 ### on_failure:
 |Allowed values|Description|
 |-|-|
 |:finish_him|action stops execution if `fail` method returns falsy value|
 |symbol with next step name|step with specified symbol name performs if step method returns falsy value|
+|:PASS|will direct execution flow to nearest success track step. If current step is the last step when action will finish as `success`|
+|:FAIL|will direct execution flow to nearest failure track step. If current step is the last step when action will finish as `failure`|
 
 ### on_failure: :finish_him
 
@@ -693,6 +767,75 @@ fail(step_name, **options)
 
 ***
 
+### on_failure: :PASS
+
+<details><summary><b>EXAMPLE (CLICK ME)</b></summary>
+<p>
+
+  ```ruby
+    require 'decouplio'
+  class SomeActionOnFailurePass < Decouplio::Action
+    logic do
+      step :step_one
+      fail :fail_one, on_failure: :PASS
+    end
+
+    def step_one(**)
+      false
+    end
+
+    def fail_one(fail_one_param:, **)
+      ctx[:fail_one] = fail_one_param
+    end
+  end
+
+  fail_step_success = SomeActionOnFailurePass.call(fail_one_param: true)
+  fail_step_failure = SomeActionOnFailurePass.call(fail_one_param: false)
+
+  fail_step_success # =>
+  # Result: failure
+
+  # Railway Flow:
+  #   step_one -> fail_one
+
+  # Context:
+  #   :fail_one_param => true
+  #   :fail_one => true
+
+  # Errors:
+  #   {}
+
+  fail_step_failure # =>
+  # Result: success
+
+  # Railway Flow:
+  #   step_one -> fail_one
+
+  # Context:
+  #   :fail_one_param => false
+  #   :fail_one => false
+
+  # Errors:
+  #   {}
+  ```
+
+  ```mermaid
+  flowchart LR
+      1(start)-->2(step_one);
+      2(step_one)-->|failure track|3(fail_one);
+      3(fail_one)-->|failure track|4(finish_failure);
+      3(fail_one)-->|on_failure: :PASS|5(finish_success);
+  ```
+</p>
+</details>
+
+***
+
+### on_failure: :FAIL
+It will perform like regular `fail` step, just move to next failure track step.
+
+***
+
 ### if: condition method name
 Can be used in case if for some reason step shouldn't be executed
 

data/docs/fail.rb

@@ -26,7 +26,7 @@ end
 success_action = SomeAction.call(param_for_step_one: true)
 failure_action = SomeAction.call(param_for_step_one: false)
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -39,7 +39,7 @@ puts success_action # =>
 #   {}
 
 
-puts failure_action # =>
+failure_action # =>
 # Result: failure
 
 # Railway Flow:
@@ -86,7 +86,7 @@ fail_step_failure = SomeActionOnSuccessFinishHim.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -98,7 +98,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -110,7 +110,7 @@ puts fail_step_success # =>
 # Errors:
 #   {}
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:
@@ -162,7 +162,7 @@ fail_step_failure = SomeActionOnSuccessToSuccessTrack.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -174,7 +174,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: success
 
 # Railway Flow:
@@ -186,7 +186,7 @@ puts fail_step_success # =>
 # Errors:
 #   {}
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:
@@ -243,7 +243,7 @@ fail_step_failure = SomeActionOnSuccessToFailureTrack.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -256,7 +256,7 @@ puts success_action # =>
 #   {}
 
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -269,7 +269,7 @@ puts fail_step_success # =>
 #   {}
 
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:
@@ -283,6 +283,56 @@ puts fail_step_failure  # =>
 
 
 
+# on_success: :PASS
+class SomeActionOnSuccessPass < Decouplio::Action
+  logic do
+    step :step_one
+    fail :fail_one, on_success: :PASS
+  end
+
+  def step_one(**)
+    ctx[:step_one] = false
+  end
+
+  def fail_one(fail_one_param:, **)
+    ctx[:fail_one] = fail_one_param
+  end
+end
+
+fail_step_success = SomeActionOnSuccessPass.call(fail_one_param: true)
+fail_step_failure = SomeActionOnSuccessPass.call(fail_one_param: false)
+
+fail_step_success # =>
+# Result: success
+
+# Railway Flow:
+#   step_one -> fail_one
+
+# Context:
+#   :fail_one_param => true
+#   :step_one => false
+#   :fail_one => true
+
+# Errors:
+#   {}
+
+fail_step_failure # =>
+# Result: failure
+
+# Railway Flow:
+#   step_one -> fail_one
+
+# Context:
+#   :fail_one_param => false
+#   :step_one => false
+#   :fail_one => false
+
+# Errors:
+#   {}
+
+
+
+
 # on_failure: :finish_him
 class SomeActionOnFailureFinishHim < Decouplio::Action
   logic do
@@ -321,7 +371,7 @@ fail_step_failure = SomeActionOnFailureFinishHim.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -334,7 +384,7 @@ puts success_action # =>
 #   {}
 
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -347,7 +397,7 @@ puts fail_step_success # =>
 #   {}
 
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:
@@ -399,7 +449,7 @@ fail_step_failure = SomeActionOnFailureToSuccessTrack.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -411,7 +461,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -424,7 +474,7 @@ puts fail_step_success # =>
 #   {}
 
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: success
 
 # Railway Flow:
@@ -481,7 +531,7 @@ fail_step_failure = SomeActionOnFailureToFailureTrack.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -492,7 +542,7 @@ puts success_action # =>
 
 # Errors:
 #   {}
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -503,7 +553,7 @@ puts fail_step_success # =>
 
 # Errors:
 #   {}
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:
@@ -517,6 +567,53 @@ puts fail_step_failure  # =>
 
 
 
+# on_failure: :PASS
+class SomeActionOnFailurePass < Decouplio::Action
+  logic do
+    step :step_one
+    fail :fail_one, on_failure: :PASS
+  end
+
+  def step_one(**)
+    false
+  end
+
+  def fail_one(fail_one_param:, **)
+    ctx[:fail_one] = fail_one_param
+  end
+end
+
+fail_step_success = SomeActionOnFailurePass.call(fail_one_param: true)
+fail_step_failure = SomeActionOnFailurePass.call(fail_one_param: false)
+
+fail_step_success # =>
+# Result: failure
+
+# Railway Flow:
+#   step_one -> fail_one
+
+# Context:
+#   :fail_one_param => true
+#   :fail_one => true
+
+# Errors:
+#   {}
+
+fail_step_failure # =>
+# Result: success
+
+# Railway Flow:
+#   step_one -> fail_one
+
+# Context:
+#   :fail_one_param => false
+#   :fail_one => false
+
+# Errors:
+#   {}
+
+
+
 # if: condition method name
 class SomeActionOnIfCondition < Decouplio::Action
   logic do
@@ -564,7 +661,7 @@ fail_condition_negative = SomeActionOnIfCondition.call(
   if_condition_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -576,7 +673,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_condition_positive # =>
+fail_condition_positive # =>
 # Result: failure
 
 # Railway Flow:
@@ -588,7 +685,7 @@ puts fail_condition_positive # =>
 # Errors:
 #   {}
 
-puts fail_condition_negative  # =>
+fail_condition_negative  # =>
 # Result: failure
 
 # Railway Flow:
@@ -649,7 +746,7 @@ fail_condition_negative = SomeActionOnUnlessCondition.call(
   if_condition_param: true
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -661,7 +758,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_condition_positive # =>
+fail_condition_positive # =>
 # Result: failure
 
 # Railway Flow:
@@ -673,7 +770,7 @@ puts fail_condition_positive # =>
 # Errors:
 #   {}
 
-puts fail_condition_negative  # =>
+fail_condition_negative  # =>
 # Result: failure
 
 # Railway Flow:
@@ -725,7 +822,7 @@ fail_step_failure = SomeActionFinishHimTrue.call(
   fail_one_param: false
 )
 
-puts success_action # =>
+success_action # =>
 # Result: success
 
 # Railway Flow:
@@ -737,7 +834,7 @@ puts success_action # =>
 # Errors:
 #   {}
 
-puts fail_step_success # =>
+fail_step_success # =>
 # Result: failure
 
 # Railway Flow:
@@ -749,7 +846,7 @@ puts fail_step_success # =>
 # Errors:
 #   {}
 
-puts fail_step_failure  # =>
+fail_step_failure  # =>
 # Result: failure
 
 # Railway Flow:

data/docs/resq.md

@@ -41,7 +41,7 @@ resq(**options)
 
 ## Behavior
 
-When `resq` step is defined after allowed step then it will catch error with class specified in options and call handler method.
+When `resq` step is defined after allowed step then it will catch error with class specified in options and call handler method. `resq` applies only for step which is defined above.
 
 <details><summary><b>EXAMPLE (CLICK ME)</b></summary>
 <p>
@@ -143,7 +143,7 @@ When `resq` step is defined after allowed step then it will catch error with cla
       logic do
         step :step_one
         resq handler_method_one: [ArgumentError, NoMethodError],
-            handler_method_two: NotImplementedError
+             handler_method_two: NotImplementedError
         step :step_two
         fail :fail_one
       end