trailblazer-macro 2.1.0.beta1

data/lib/trailblazer/operation/rescue.rb

@@ -0,0 +1,42 @@
+class Trailblazer::Operation
+  NoopHandler = lambda { |*| }
+
+  def self.Rescue(*exceptions, handler: NoopHandler, &block)
+    exceptions = [StandardError] unless exceptions.any?
+
+    handler    = Rescue.deprecate_positional_handler_signature(handler)
+    handler    = Trailblazer::Option(handler)
+
+    # This block is evaluated by {Wrap}.
+    rescue_block = ->((ctx, flow_options), **circuit_options, &nested_activity) do
+      begin
+        nested_activity.call
+      rescue *exceptions => exception
+        # DISCUSS: should we deprecate this signature and rather apply the Task API here?
+        handler.call(exception, ctx, **circuit_options) # FIXME: when there's an error here, it shows the wrong exception!
+
+        [ Trailblazer::Operation::Railway.fail!, [ctx, flow_options] ]
+      end
+    end
+
+    Wrap( rescue_block, id: "Rescue(#{rand(100)})", &block )
+    # FIXME: name
+    # [ step, name: "Rescue:#{block.source_location.last}" ]
+  end
+
+  # TODO: remove me in 2.2.
+  module Rescue
+    def self.deprecate_positional_handler_signature(handler)
+      return handler if handler.is_a?(Symbol) # can't do nutting about this.
+
+      arity = handler.is_a?(Class) ? handler.method(:call).arity : handler.arity
+
+      return handler if arity != 2 # means (exception, (ctx, flow_options), *, &block), "new style"
+
+      ->(exception, (ctx, flow_options), **circuit_options, &block) do
+        warn "[Trailblazer] Rescue handlers have a new signature: (exception, *, &block)"
+        handler.(exception, ctx, &block)
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/wrap.rb

@@ -0,0 +1,83 @@
+class Trailblazer::Operation
+  def self.Wrap(user_wrap, id: "Wrap/#{rand(100)}", &block)
+    operation_class = Wrap.create_operation(block)
+    wrapped         = Wrap::Wrapped.new(operation_class, user_wrap)
+
+    { task: wrapped, id: id, outputs: operation_class.outputs }
+  end
+
+  module Wrap
+    def self.create_operation(block)
+      Class.new( Nested.operation_class, &block ) # Usually resolves to Trailblazer::Operation.
+    end
+
+    # behaves like an operation so it plays with Nested and simply calls the operation in the user-provided block.
+    class Wrapped #< Trailblazer::Operation # FIXME: the inheritance is only to satisfy Nested( Wrapped.new )
+      include Trailblazer::Activity::Interface
+
+      private def deprecate_positional_wrap_signature(user_wrap)
+        parameters = user_wrap.is_a?(Class) ? user_wrap.method(:call).parameters : user_wrap.parameters
+
+        return user_wrap if parameters[0] == [:req] # means ((ctx, flow_options), *, &block), "new style"
+
+        ->((ctx, flow_options), **circuit_options, &block) do
+          warn "[Trailblazer] Wrap handlers have a new signature: ((ctx), *, &block)"
+          user_wrap.(ctx, &block)
+        end
+      end
+
+      def initialize(operation, user_wrap)
+        user_wrap = deprecate_positional_wrap_signature(user_wrap)
+
+        @operation  = operation
+        @user_wrap  = user_wrap
+
+        # Since in the user block, you can return Railway.pass! etc, we need to map
+        # those to the actual wrapped operation's end.
+        outputs           = @operation.outputs
+        @signal_to_output = {
+          Railway.pass!      => outputs[:success].signal,
+          Railway.fail!      => outputs[:failure].signal,
+          Railway.pass_fast! => outputs[:pass_fast].signal,
+          Railway.fail_fast! => outputs[:fail_fast].signal,
+          true               => outputs[:success].signal,
+          false              => outputs[:failure].signal,
+          nil                => outputs[:failure].signal,
+        }
+      end
+
+      def call( (ctx, flow_options), **circuit_options )
+        block_calling_wrapped = -> {
+          activity = @operation.to_h[:activity]
+
+          activity.( [ctx, flow_options], **circuit_options )
+        }
+
+        # call the user's Wrap {} block in the operation.
+        # This will invoke block_calling_wrapped above if the user block yields.
+        returned = @user_wrap.( [ctx, flow_options], **circuit_options, &block_calling_wrapped )
+
+        # {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.
+          signal, (ctx, flow_options) = returned
+        else                     # 2. {task interface return}, only a signal (or true/false)
+          # TODO: deprecate this?
+          signal = returned
+        end
+
+        # Use the original {signal} if there's no mapping.
+        # This usually means signal is an End instance or a custom signal.
+        signal = @signal_to_output.fetch(signal, signal)
+
+        return signal, [ctx, flow_options]
+      end
+
+      def outputs
+        @operation.outputs
+      end
+    end
+  end # Wrap
+end

data/test/docs/guard_test.rb

@@ -0,0 +1,162 @@
+require "test_helper"
+
+#--
+# with proc
+class DocsGuardProcTest < Minitest::Spec
+  #:proc
+  class Create < Trailblazer::Operation
+    step Policy::Guard(->(options, pass:, **) { pass })
+    #~pipeonly
+    step :process
+
+    def process(options, **)
+      options["x"] = true
+    end
+    #~pipeonly end
+  end
+  #:proc end
+
+  it { Create.(pass: false)["x"].must_be_nil }
+  it { Create.(pass: true)["x"].must_equal true }
+
+  #- result object, guard
+  it { Create.(pass: true)["result.policy.default"].success?.must_equal true }
+  it { Create.(pass: false)["result.policy.default"].success?.must_equal false }
+
+  #---
+  #- Guard inheritance
+  class New < Create
+    step Policy::Guard( ->(options, current_user:, **) { current_user } ), override: true
+  end
+
+  it { Trailblazer::Operation::Inspect.(New).must_equal %{[>policy.default.eval,>process]} }
+end
+
+#---
+# with Callable
+class DocsGuardTest < Minitest::Spec
+  #:callable
+  class MyGuard
+    include Uber::Callable
+
+    def call(options, pass:, **)
+      pass
+    end
+  end
+  #:callable end
+
+  #:callable-op
+  class Create < Trailblazer::Operation
+    step Policy::Guard( MyGuard.new )
+    #~pipe-only
+    step :process
+
+    def process(options, **)
+      options[:x] = true
+    end
+    #~pipe-only end
+  end
+  #:callable-op end
+
+  it { Create.(pass: false)[:x].must_be_nil }
+  it { Create.(pass: true)[:x].must_equal true }
+end
+
+#---
+# with method
+class DocsGuardMethodTest < Minitest::Spec
+  #:method
+  class Create < Trailblazer::Operation
+    step Policy::Guard( :pass? )
+
+    def pass?(options, pass:, **)
+      pass
+    end
+    #~pipe-onlyy
+    step :process
+
+    def process(options, **)
+      options["x"] = true
+    end
+    #~pipe-onlyy end
+  end
+  #:method end
+
+  it { Create.(pass: false).inspect("x").must_equal %{<Result:false [nil] >} }
+  it { Create.(pass: true).inspect("x").must_equal %{<Result:true [true] >} }
+end
+
+#---
+# with name:
+class DocsGuardNamedTest < Minitest::Spec
+  #:name
+  class Create < Trailblazer::Operation
+    step Policy::Guard( ->(options, current_user:, **) { current_user }, name: :user )
+    # ...
+  end
+  #:name end
+
+  it { Create.(:current_user => nil   )["result.policy.user"].success?.must_equal false }
+  it { Create.(:current_user => Module)["result.policy.user"].success?.must_equal true }
+
+  it {
+  #:name-result
+  result = Create.(:current_user => true)
+  result["result.policy.user"].success? #=> true
+  #:name-result end
+  }
+end
+
+#---
+# dependency injection
+class DocsGuardInjectionTest < Minitest::Spec
+  #:di-op
+  class Create < Trailblazer::Operation
+    step Policy::Guard( ->(options, current_user:, **) { current_user == Module } )
+  end
+  #:di-op end
+
+  it { Create.(:current_user => Module).inspect("").must_equal %{<Result:true [nil] >} }
+  it {
+    result =
+  #:di-call
+  Create.({},
+    :current_user        => Module,
+    "policy.default.eval" => Trailblazer::Operation::Policy::Guard.build(->(options, **) { false })
+  )
+  #:di-call end
+    result.inspect("").must_equal %{<Result:false [nil] >} }
+end
+
+#---
+# missing current_user throws exception
+class DocsGuardMissingKeywordTest < Minitest::Spec
+  class Create < Trailblazer::Operation
+    step Policy::Guard( ->(options, current_user:, **) { current_user == Module } )
+  end
+
+  it { assert_raises(ArgumentError) { Create.() } }
+  it { Create.(:current_user => Module).success?.must_equal true }
+end
+
+#---
+# before:
+class DocsGuardPositionTest < Minitest::Spec
+  #:before
+  class Create < Trailblazer::Operation
+    step :model!
+    step Policy::Guard( :authorize! ),
+      before: :model!
+  end
+  #:before end
+
+  it { Trailblazer::Operation::Inspect.(Create).must_equal %{[>policy.default.eval,>model!]} }
+  it do
+    #:before-pipe
+      Trailblazer::Operation::Inspect.(Create, style: :rows) #=>
+       # 0 ========================>operation.new
+       # 1 ==================>policy.default.eval
+       # 2 ===============================>model!
+    #:before-pipe end
+  end
+end

data/test/docs/macro_test.rb

@@ -0,0 +1,36 @@
+require "test_helper"
+
+class DocsMacroTest < Minitest::Spec
+  #:simple
+  module Macro
+    def self.MyPolicy(allowed_role: "admin")
+      step = ->(input, options) { options["current_user"].type == allowed_role }
+
+      [ step, name: "my_policy.#{allowed_role}" ] # :before, :replace, etc. work, too.
+    end
+  end
+  #:simple end
+
+  #:simple-op
+  class Create < Trailblazer::Operation
+    step Macro::MyPolicy( allowed_role: "manager" )
+    # ..
+  end
+  #:simple-op end
+
+=begin
+  it do
+  #:simple-pipe
+    puts Create["pipetree"].inspect(style: :rows) #=>
+     0 ========================>operation.new
+     1 ====================>my_policy.manager
+  #:simple-pipe end
+  end
+=end
+
+  it { Operation::Inspect.(Create).must_equal %{[>my_policy.manager]} }
+end
+
+# injectable option
+# nested pipe
+# using macros in macros

data/test/docs/model_test.rb

@@ -0,0 +1,75 @@
+require "test_helper"
+
+class DocsModelTest < Minitest::Spec
+  Song = Struct.new(:id, :title) do
+    def self.find_by(id:nil)
+      id.nil? ? nil : new(id)
+    end
+
+    def self.[](id)
+      id.nil? ? nil : new(id+99)
+    end
+  end
+
+  #:op
+  class Create < Trailblazer::Operation
+    step Model( Song, :new )
+    # ..
+  end
+  #:op end
+
+  it do
+    #:create
+    result = Create.(params: {})
+    result[:model] #=> #<struct Song id=nil, title=nil>
+    #:create end
+
+    result[:model].inspect.must_equal %{#<struct DocsModelTest::Song id=nil, title=nil>}
+  end
+
+  #:update
+  class Update < Trailblazer::Operation
+    step Model( Song, :find_by )
+    # ..
+  end
+  #:update end
+
+  it do
+    #:update-ok
+    result = Update.(params: { id: 1 })
+    result[:model] #=> #<struct Song id=1, title="Roxanne">
+    #:update-ok end
+
+    result[:model].inspect.must_equal %{#<struct DocsModelTest::Song id=1, title=nil>}
+  end
+
+  it do
+    #:update-fail
+    result = Update.(params: {})
+    result[:model] #=> nil
+    result.success? #=> false
+    #:update-fail end
+
+    result[:model].must_be_nil
+    result.success?.must_equal false
+  end
+
+  #:show
+  class Show < Trailblazer::Operation
+    step Model( Song, :[] )
+    # ..
+  end
+  #:show end
+
+  it do
+    result = Show.(params: { id: 1 })
+
+    #:show-ok
+    result = Show.(params: { id: 1 })
+    result[:model] #=> #<struct Song id=1, title="Roxanne">
+    #:show-ok end
+
+    result.success?.must_equal true
+    result[:model].inspect.must_equal %{#<struct DocsModelTest::Song id=100, title=nil>}
+  end
+end

data/test/docs/nested_test.rb

@@ -0,0 +1,113 @@
+require "test_helper"
+
+class NestedInput < Minitest::Spec
+  #:input-multiply
+  class Multiplier < Trailblazer::Operation
+    step ->(options, x:, y:, **) { options["product"] = x*y }
+  end
+  #:input-multiply end
+
+  #:input-pi
+  class MultiplyByPi < Trailblazer::Operation
+    step ->(options, **) { options["pi_constant"] = 3.14159 }
+    step Nested( Multiplier, input: ->(options, **) do
+      { "y" => options["pi_constant"],
+        "x" => options["x"]
+      }
+    end )
+  end
+  #:input-pi end
+
+  it { MultiplyByPi.("x" => 9).inspect("product").must_equal %{<Result:true [28.27431] >} }
+
+  it do
+    #:input-result
+    result = MultiplyByPi.("x" => 9)
+    result["product"] #=> [28.27431]
+    #:input-result end
+  end
+end
+
+class NestedInputCallable < Minitest::Spec
+  Multiplier = NestedInput::Multiplier
+
+  #:input-callable
+  class MyInput
+    def self.call(options, **)
+      {
+        "y" => options["pi_constant"],
+        "x" => options["x"]
+      }
+    end
+  end
+  #:input-callable end
+
+  #:input-callable-op
+  class MultiplyByPi < Trailblazer::Operation
+    step ->(options, **) { options["pi_constant"] = 3.14159 }
+    step Nested( Multiplier, input: MyInput )
+  end
+  #:input-callable-op end
+
+  it { MultiplyByPi.("x" => 9).inspect("product").must_equal %{<Result:true [28.27431] >} }
+end
+
+class NestedWithCallableAndInputTest < Minitest::Spec
+  Memo = Struct.new(:title, :text, :created_by)
+
+  class Memo::Upsert < Trailblazer::Operation
+    step Nested( :operation_class, input: :input_for_create )
+
+    def operation_class( ctx, ** )
+      ctx[:id] ? Update : Create
+    end
+
+    # only let :title pass through.
+    def input_for_create( ctx )
+      { title: ctx[:title] }
+    end
+
+    class Create < Trailblazer::Operation
+      step :create_memo
+
+      def create_memo( ctx, ** )
+        ctx[:model] = Memo.new(ctx[:title], ctx[:text], :create)
+      end
+    end
+
+    class Update < Trailblazer::Operation
+      step :find_by_title
+
+      def find_by_title( ctx, ** )
+        ctx[:model] = Memo.new(ctx[:title], ctx[:text], :update)
+      end
+    end
+  end
+
+  it "runs Create without :id" do
+    Memo::Upsert.( title: "Yay!" ).inspect(:model).
+      must_equal %{<Result:true [#<struct NestedWithCallableAndInputTest::Memo title=\"Yay!\", text=nil, created_by=:create>] >}
+  end
+
+  it "runs Update without :id" do
+    Memo::Upsert.( id: 1, title: "Yay!" ).inspect(:model).
+      must_equal %{<Result:true [#<struct NestedWithCallableAndInputTest::Memo title=\"Yay!\", text=nil, created_by=:update>] >}
+  end
+end
+
+# builder: Nested + deviate to left if nil / skip_track if true
+
+#---
+# automatic :name
+class NestedNameTest < Minitest::Spec
+  class Create < Trailblazer::Operation
+    class Present < Trailblazer::Operation
+      # ...
+    end
+
+    step Nested( Present )
+    # ...
+  end
+
+  it { Operation::Inspect.(Create).must_equal %{[>Nested(NestedNameTest::Create::Present)]} }
+end