coming from the user handler in Wrap(), we no longer map random signals like true

or nil to actual signals. this has never been official, anyways, and is not deprecated.

Author: apotonick

CHANGES.md

@@ -9,6 +9,24 @@ Inject(:composer_index) => ->(ctx, index:, **) { index },
 * Remove deprecation for `Nested(Memo::Operation::Create)`. Without a dynamic decider, use `Subprocess()`.
 * Rename `:auto_wire` option in `Nested()` to `:static`.
 
+## Wrap
+
+* Silently deprecate the "feature" to return arbitrary "signals" from the user handler.
+  Before 2.2, you could do things like
+
+  ```ruby
+  class HandleUnsafeProcess
+    def self.call(ctx, flow_options, _circuit_options, &block)
+      yield
+    rescue
+      true # Or any other object that will be treated as a signal.
+    end
+  end
+  ```
+
+  As this has never been officially documented, you won't be warned about the deprecation. =========> consistency
+
+
 # 2.1.16
 
 * Fix a bug in `patch` where `Subprocess()` was missing in `Macro::Strategy`.

lib/trailblazer/macro/wrap.rb

@@ -8,16 +8,13 @@ def self.Wrap(user_wrap, id: Macro.id_for(user_wrap, macro: :Wrap), &block)
 
       outputs   = Hash[outputs.collect { |output| [output.semantic, output] }] # FIXME: redundant to Subprocess().
 
-      # Since in the user block, you can return Railway.pass! etc, we need to map
-      # those to the actual wrapped block_activity's end.
+      # Since in the user block, you can return Railway.pass! etc, we need to translate
+      # those to the actual block_activity's termini.
       signal_to_output = {
         Activity::Right               => outputs[:success].signal,
         Activity::Left                => outputs[:failure].signal,
         Activity::FastTrack::PassFast => outputs[:pass_fast].signal,
         Activity::FastTrack::FailFast => outputs[:fail_fast].signal,
-        true               => outputs[:success].signal,
-        false              => outputs[:failure].signal,
-        nil                => outputs[:failure].signal,
       }
 
       state = Declarative::State(
@@ -45,31 +42,20 @@ def self.Wrap(user_wrap, id: Macro.id_for(user_wrap, macro: :Wrap), &block)
     class Wrap < Macro::Strategy
       def self.call(ctx, flow_options, circuit_options)
         # since yield is called without arguments, we need to pull default params from here. Oh ... tricky.
-
         block_called_from_user_yield = ->() { # DISCUSS: because we allow users to call {yield}, we don't receive any args here.
           Activity::Circuit::Runner.(block_activity, ctx, flow_options, circuit_options)
         }
 
-        # call the user's Wrap {} block in the operation.
-        # This will invoke block_called_from_user_yield above if the user block yields.
         user_handler = @state.get(:user_wrap)
 
         # Invoke the user's handler.
-        returned = user_handler.(ctx, flow_options, circuit_options, &block_called_from_user_yield)
-
-        # {returned} can be
-        #   1. {circuit interface return} from the begin block, because the wrapped OP passed
-        #   2. {task interface return} because the user block returns "customized" signals, true of fale
-
-        if returned.is_a?(Array) # 1. {circuit interface return}, new style.
-          ctx, flow_options, signal = returned
-        else                     # 2. {task interface return}, only a signal (or true/false)
-          # TODO: deprecate this?
-          signal = returned
-        end
+        ctx, flow_options, signal = user_handler.(ctx, flow_options, circuit_options, &block_called_from_user_yield)
 
-        # If there's no mapping, use the original {signal} .
-        # This usually means signal is a terminus or a custom signal.
+        # The user handler is allowed to return signals like Right and Left. We need to translate
+        # those to termini signals from the block_activity, cause those are the only ones
+        # we route.
+        # DISCUSS: i would love to skip this, but that'd mean the user has to return a
+        #          "native" signal from their block.
         signal = @state.get(:signal_to_output).fetch(signal, signal)
 
         return ctx, flow_options, signal

test/docs/wrap_test.rb

@@ -12,6 +12,8 @@ def self.call(ctx, flow_options, _circuit_options, &block) # FIXME: deprecate th
 end
 #:my_transaction end
 
+# TODO: add 2.1 version of the above
+
 class WrapSimpleHandlerTest < Minitest::Spec
   MyTransaction = ::MyTransaction
 
@@ -315,7 +317,7 @@ class MyTransaction
       def self.call(ctx, flow_options, _circuit_options, &block)
         yield # calls the wrapped steps
       rescue
-        MyFailSignal
+        return ctx, flow_options, MyFailSignal
       end
     end
     #:custom-handler end
@@ -389,7 +391,7 @@ class HandleUnsafeProcess
         def self.call(ctx, flow_options, _circuit_options, &block)
           yield # calls the wrapped steps
         rescue
-          true
+          return ctx, flow_options, Trailblazer::Activity::Right
         end
       end
 
@@ -425,7 +427,7 @@ class HandleUnsafeProcess
         def self.call(ctx, flow_options, _circuit_options, &block)
           yield # calls the wrapped steps
         rescue
-          false
+          return ctx, flow_options, Trailblazer::Activity::Left
         end
       end
 
@@ -448,42 +450,6 @@ def self.call(ctx, flow_options, _circuit_options, &block)
     end
   end
 
-=begin
-When success: return the block's returns
-When raise:   return {nil} and go "failed"
-You can return nil in wrap.
-=end
-  class WrapGoesIntoNilFromRescueTest < Minitest::Spec
-    Memo = Module.new
-
-    class Memo::Create < Trailblazer::Operation
-      class HandleUnsafeProcess
-        def self.call(ctx, flow_options, _circuit_options, &block)
-          yield # calls the wrapped steps
-        rescue
-          nil
-        end
-      end
-
-      step :model
-      step Wrap( HandleUnsafeProcess ) {
-        step :update
-        step :rehash
-      }
-      step :notify
-      left :log_error
-
-      #~methods
-      include T.def_steps(:model, :update, :notify, :log_error)
-      include Rehash
-      #~methods end
-    end
-
-    it "translates nil returned form a wrap to a signal with a `failure` semantic" do
-      assert_call Memo::Create, seq: "[:model, :update, :rehash, :log_error]", rehash_raise: RuntimeError, terminus: :failure
-    end
-  end
-
 =begin
 When success: return the block's returns
 When raise:   return {Railway.fail!}