trailblazer-operation 0.0.13 → 0.4.1

data/lib/trailblazer/operation/public_call.rb

@@ -0,0 +1,55 @@
+module Trailblazer
+  module Operation::PublicCall
+    # This is the outer-most public `call` method that gets invoked when calling `Create.()`.
+    # The signature of this is `params, options, *containers`. This was a mistake, as the
+    # first argument could've been part of `options` hash in the first place.
+    #
+    # Create.(params, runtime_data, *containers)
+    #   #=> Result<Context...>
+    #
+    # In workflows/Nested compositions, this method is not used anymore and it might probably
+    # get removed in future versions of TRB. Currently, we use Operation::__call__ as an alternative.
+    #
+    #
+    # @note Do not override this method as it will be removed in future versions. Also, you will break tracing.
+    # @return Operation::Railway::Result binary result object
+    def call(*args)
+      return call_with_circuit_interface(*args) if args.any? && args[0].is_a?(Array) # This is kind of a hack that could be well hidden if Ruby had method overloading. Goal is to simplify the call/__call__ thing as we're fading out Operation::call anyway.
+      call_with_public_interface(*args)
+    end
+
+    def call_with_public_interface(*args)
+      ctx = Operation::PublicCall.options_for_public_call(*args)
+
+      # call the activity.
+      # This will result in invoking {::call_with_circuit_interface}.
+      last_signal, (options, flow_options) = Activity::TaskWrap.invoke(self, [ctx, {}], {})
+
+      # Result is successful if the activity ended with an End event derived from Railway::End::Success.
+      Operation::Railway::Result(last_signal, options, flow_options)
+    end
+
+    # This interface is used for all nested OPs (and the outer-most, too).
+    def call_with_circuit_interface(args, circuit_options)
+      @activity.(
+        args,
+        circuit_options.merge(
+          exec_context: new
+        )
+      )
+    end
+
+    # Compile a Context object to be passed into the Activity::call.
+    # @private
+    def self.options_for_public_call(options={}, *containers)
+      # generate the skill hash that embraces runtime options plus potential containers, the so called Runtime options.
+      # This wrapping is supposed to happen once in the entire system.
+
+      hash_transformer = ->(containers) { containers[0].to_hash } # FIXME: don't transform any containers into kw args.
+
+      immutable_options = Trailblazer::Context::ContainerChain.new( [options, *containers], to_hash: hash_transformer ) # Runtime options, immutable.
+
+      ctx = Trailblazer::Context(immutable_options)
+    end
+  end
+end

data/lib/trailblazer/operation/railway.rb

@@ -0,0 +1,32 @@
+module Trailblazer
+  # Operations is simply a thin API to define, inherit and run circuits by passing the options object.
+  # It encourages the linear railway style (http://trb.to/gems/workflow/circuit.html#operation) but can
+  # easily be extend for more complex workflows.
+  class Operation
+    # End event: All subclasses of End:::Success are interpreted as "success".
+    module Railway
+      # @param options Context
+      # @param end_event The last emitted signal in a circuit is usually the end event.
+      def self.Result(end_event, options, *)
+        Result.new(end_event.kind_of?(End::Success), options, end_event)
+      end
+
+      # The Railway::Result knows about its binary state, the context (data), and the last event in the circuit.
+      class Result < Result # Operation::Result
+        def initialize(success, data, event)
+          super(success, data)
+
+          @event = event
+        end
+
+        attr_reader :event
+      end
+
+      module End
+        class Success < Activity::End; end
+        class Failure < Activity::End; end
+      end
+
+    end # Railway
+  end
+end

data/lib/trailblazer/operation/railway/fast_track.rb

@@ -0,0 +1,13 @@
+module Trailblazer
+  module Operation::Railway
+    def self.fail!     ; Activity::Left  end
+    def self.pass!     ; Activity::Right end
+    def self.fail_fast!; Activity::FastTrack::FailFast end
+    def self.pass_fast!; Activity::FastTrack::PassFast end
+
+    module End
+      FailFast = Class.new(Operation::Railway::End::Failure)
+      PassFast = Class.new(Operation::Railway::End::Success)
+    end
+  end
+end

data/lib/trailblazer/operation/railway/macaroni.rb

@@ -0,0 +1,23 @@
+module Trailblazer
+  module Operation::Railway
+    # Call the user's steps with a differing API (inspired by Maciej Mensfeld) that
+    # only receives keyword args. The `options` keyword is the stateful context object
+    #
+    #   def my_step( params:, ** )
+    #   def my_step( params:, options:, ** )
+    module Macaroni
+      def self.call(user_proc)
+        Activity::TaskBuilder::Task.new( Trailblazer::Option.build( Macaroni::Option, user_proc ), user_proc )
+      end
+
+      class Option < Trailblazer::Option
+        # The Option#call! method prepares the arguments.
+        def self.call!(proc, options, *)
+          proc.( **options.to_hash.merge( options: options ) )
+        end
+      end
+    end
+
+    KwSignature = Macaroni
+  end
+end

data/lib/trailblazer/operation/railway/normalizer.rb

@@ -0,0 +1,58 @@
+module Trailblazer
+  module Operation::Railway
+    # The {Normalizer} is called for every DSL call (step/pass/fail etc.) and normalizes/defaults
+    # the user options, such as setting `:id`, connecting the task's outputs or wrapping the user's
+    # task via {TaskBuilder} in order to translate true/false to `Right` or `Left`.
+    #
+    # The Normalizer sits in the `@builder`, which receives all DSL calls from the Operation subclass.
+    module Normalizer
+      Pipeline = Activity::Magnetic::Normalizer::Pipeline.clone
+
+      Pipeline.module_eval do
+        # Handle the :override option which is specific to Operation.
+        def self.override(ctx, task:, options:, sequence_options:, **)
+          options, locals  = Activity::Magnetic::Options.normalize(options, [:override])
+          sequence_options = sequence_options.merge( replace: options[:id] ) if locals[:override]
+
+          ctx[:options], ctx[:sequence_options] = options, sequence_options
+        end
+
+        # TODO remove in 2.2
+        def self.deprecate_macro_with_two_args(ctx, task:, **)
+          return true unless task.is_a?(Array) # TODO remove in 2.2
+
+          ctx[:options] = Operation::DeprecatedMacro.( *task )
+        end
+
+        # TODO remove in 2.2
+        def self.deprecate_name(ctx, local_options:, connection_options:, **)
+          connection_options, deprecated_options = Activity::Magnetic::Options.normalize(connection_options, [:name])
+          local_options, _deprecated_options     = Activity::Magnetic::Options.normalize(local_options, [:name])
+
+          deprecated_options = deprecated_options.merge(_deprecated_options)
+
+          local_options = local_options.merge( name: deprecated_options[:name] ) if deprecated_options[:name]
+
+          local_options, locals = Activity::Magnetic::Options.normalize(local_options, [:name])
+          if locals[:name]
+            warn "[Trailblazer] The :name option for #step, #success and #failure has been renamed to :id."
+            local_options = local_options.merge(id: locals[:name])
+          end
+
+          ctx[:local_options], ctx[:connection_options] = local_options, connection_options
+        end
+
+        def self.raise_on_missing_id(ctx, local_options:, **)
+          raise "No :id given for #{local_options[:task]}" unless local_options[:id]
+          true
+        end
+
+        # add more normalization tasks to the existing Magnetic::Normalizer::Pipeline
+        task Activity::TaskBuilder::Binary( method(:deprecate_macro_with_two_args) ), before: "split_options"
+        task Activity::TaskBuilder::Binary( method(:deprecate_name) )
+        task Activity::TaskBuilder::Binary( method(:override) )
+        task Activity::TaskBuilder::Binary( method(:raise_on_missing_id) )
+      end
+    end # Normalizer
+  end
+end

data/lib/trailblazer/operation/railway/task_builder.rb

@@ -0,0 +1,37 @@
+module Trailblazer
+  module Operation::Railway
+    # every step is wrapped by this proc/decider. this is executed in the circuit as the actual task.
+    # Step calls step.(options, **options, flow_options)
+    # Output direction binary: true=>Right, false=>Left.
+    # Passes through all subclasses of Direction.~~~~~~~~~~~~~~~~~
+    module TaskBuilder
+      def self.call(user_proc)
+        Task.new( Trailblazer::Option::KW( user_proc ), user_proc )
+      end
+
+      # Translates the return value of the user step into a valid signal.
+      # Note that it passes through subclasses of {Signal}.
+      def self.binary_direction_for(result, on_true, on_false)
+        result.is_a?(Class) && result < Activity::Signal ? result : (result ? on_true : on_false)
+      end
+    end
+
+    class Task
+      def initialize(task, user_proc)
+        @task      = task
+        @user_proc = user_proc
+        freeze
+      end
+
+      def call( (options, *args), **circuit_args )
+        # Execute the user step with TRB's kw args.
+        result = @task.( options, **circuit_args ) # circuit_args contains :exec_context.
+
+        # Return an appropriate signal which direction to go next.
+        direction = TaskBuilder.binary_direction_for( result, Activity::Right, Activity::Left )
+
+        [ direction, [ options, *args ], **circuit_args ]
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/result.rb

@@ -1,12 +1,11 @@
 class Trailblazer::Operation
   class Result
+    # @param success Boolean validity of the result object
+    # @param data Context
     def initialize(success, data)
-      @success, @data = success, data # @data is a Skill instance.
+      @success, @data = success, data
     end
 
-    extend Forwardable
-    def_delegators :@data, :[] # DISCUSS: make it a real delegator? see Nested.
-
     def success?
       @success
     end
@@ -15,6 +14,9 @@ class Trailblazer::Operation
       ! success?
     end
 
+    extend Forwardable
+    def_delegators :@data, :[] # DISCUSS: make it a real delegator? see Nested.
+
     # DISCUSS: the two methods below are more for testing.
     def inspect(*slices)
       return "<Result:#{success?} #{slice(*slices).inspect} >" if slices.any?

data/lib/trailblazer/operation/trace.rb

@@ -0,0 +1,46 @@
+module Trailblazer
+  class Operation
+    module Trace
+      # @note The problem in this method is, we have redundancy with Operation::PublicCall
+      def self.call(operation, *args)
+        ctx = PublicCall.options_for_public_call(*args)   # redundant with PublicCall::call.
+
+        # Prepare the tracing-specific arguments. This is only run once for the entire circuit!
+        operation, *args = Trailblazer::Activity::Trace.arguments_for_call( operation, [ctx, {}], {} )
+
+        last_signal, (ctx, flow_options) = Activity::TaskWrap.invoke(operation, *args )
+
+        result = Railway::Result(last_signal, ctx)    # redundant with PublicCall::call.
+
+        Result.new(result, flow_options[:stack].to_a)
+      end
+
+      # `Operation::trace` is included for simple tracing of the flow.
+      # It simply forwards all arguments to `Trace.call`.
+      #
+      # @public
+      #
+      #   Operation.trace(params, "current_user" => current_user).wtf
+      def trace(*args)
+        Trace.(self, *args)
+      end
+
+      # Presentation of the traced stack via the returned result object.
+      # This object is wrapped around the original result in {Trace.call}.
+      class Result < SimpleDelegator
+        def initialize(result, stack)
+          super(result)
+          @stack = stack
+        end
+
+        def wtf
+          Trailblazer::Activity::Trace::Present.(@stack)
+        end
+
+        def wtf?
+          puts wtf
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Operation
-    VERSION = "0.0.13"
+    VERSION = "0.4.1"
   end
 end

data/test/call_test.rb

@@ -1,28 +1,47 @@
 require "test_helper"
 
-# DISCUSS: do we need this test?
 class CallTest < Minitest::Spec
   describe "::call" do
     class Create < Trailblazer::Operation
+      step ->(*) { true }
       def inspect
         "#{@skills.inspect}"
       end
     end
 
-    it { Create.().must_be_instance_of Trailblazer::Operation::Result }
+    it { Create.().must_be_instance_of Trailblazer::Operation::Railway::Result }
 
-    it { Create.({}).inspect.must_equal %{<Result:true <Skill {} {\"params\"=>{}} {\"pipetree\"=>[>operation.new]}> >} }
-    it { Create.(name: "Jacob").inspect.must_equal %{<Result:true <Skill {} {\"params\"=>{:name=>\"Jacob\"}} {\"pipetree\"=>[>operation.new]}> >} }
-    it { Create.({ name: "Jacob" }, { policy: Object }).inspect.must_equal %{<Result:true <Skill {} {:policy=>Object, \"params\"=>{:name=>\"Jacob\"}} {\"pipetree\"=>[>operation.new]}> >} }
+    # it { Create.({}).inspect.must_equal %{<Result:true <Skill {} {\"params\"=>{}} {\"pipetree\"=>[>operation.new]}> >} }
+    # it { Create.(name: "Jacob").inspect.must_equal %{<Result:true <Skill {} {\"params\"=>{:name=>\"Jacob\"}} {\"pipetree\"=>[>operation.new]}> >} }
+    # it { Create.({ name: "Jacob" }, { policy: Object }).inspect.must_equal %{<Result:true <Skill {} {:policy=>Object, \"params\"=>{:name=>\"Jacob\"}} {\"pipetree\"=>[>operation.new]}> >} }
 
     #---
     # success?
     class Update < Trailblazer::Operation
-      step ->(options) { options["params"] }, after: "operation.new"
+      step ->(options, **) { options[:result] }
+    end
+
+    # operation success
+    it do
+      result = Update.(result: true)
+
+      result.success?.must_equal true
+
+      result.event.must_be_instance_of Trailblazer::Operation::Railway::End::Success
+      result.event.must_equal Update.outputs[:success].signal
+    end
+
+    # operation failure
+    it do
+      result = Update.(result: false)
+
+      result.success?.must_equal false
+      result.failure?.must_equal true
+
+      result.event.must_be_instance_of Trailblazer::Operation::Railway::End::Failure
+      result.event.must_equal Update.outputs[:failure].signal
     end
 
-    it { Update.(true).success?.must_equal true }
-    it { Update.(false).success?.must_equal false }
   end
 end
 

data/test/callable_test.rb

@@ -0,0 +1,147 @@
+require "test_helper"
+
+class CallableHelper < Minitest::Spec
+  Operation = Trailblazer::Operation
+  Activity  = Trailblazer::Activity
+
+  module Blog
+    Read    = ->((options, *args), *) { options["Read"] = 1; [ Activity::Right, [options, *args] ] }
+    Next    = ->((options, *args), *) { options["NextPage"] = []; [ options["return"], [options, *args] ] }
+    Comment = ->((options, *args), *) { options["Comment"] = 2; [ Activity::Right, [options, *args] ] }
+  end
+
+  module User
+    Relax   = ->((options, *args), *) { options["Relax"]=true; [ Activity::Right, [options, *args] ] }
+  end
+
+  ### Callable( )
+  ###
+  describe "circuit with 1 level of nesting" do # TODO: test this kind of configuration in dsl_tests somewhere.
+    let(:blog) do
+      Module.new do
+        extend Activity::Path()
+
+        task task: Blog::Read
+        task task: Blog::Next, Output(Activity::Right, :done) => "End.success", Output(Activity::Left, :success) => Track(:success)
+        task task: Blog::Comment
+      end
+    end
+
+    let(:user) do
+      _blog = blog
+
+      Module.new do
+        extend Activity::Path()
+
+        task task: _blog, _blog.outputs[:success] => Track(:success)
+        task task: User::Relax
+      end
+    end
+
+    it "ends before comment, on next_page" do
+      user.( [options = { "return" => Activity::Right }] ).must_equal(
+        [user.outputs[:success].signal, [{"return"=>Trailblazer::Activity::Right, "Read"=>1, "NextPage"=>[], "Relax"=>true}]]
+      )
+
+      options.must_equal({"return"=>Trailblazer::Activity::Right, "Read"=>1, "NextPage"=>[], "Relax"=>true})
+    end
+  end
+
+  ### Callable( End1, End2 )
+  ###
+  describe "circuit with 2 end events in the nested process" do
+    let(:blog) do
+      Module.new do
+        extend Activity::Path()
+
+        task task: Blog::Read
+        task task: Blog::Next, Output(Activity::Right, :success___) => :__success, Output(Activity::Left, :retry___) => _retry=End(:retry)
+      end
+    end
+
+    let(:user) do
+      _blog = blog
+
+      Module.new do
+        extend Activity::Path()
+
+        task task: _blog, _blog.outputs[:success] => Track(:success), _blog.outputs[:retry] => "End.success"
+        task task: User::Relax
+      end
+    end
+
+    it "runs from Callable->default to Relax" do
+      user.( [ options = { "return" => Activity::Right } ] ).must_equal [
+        user.outputs[:success].signal,
+        [ {"return"=>Activity::Right, "Read"=>1, "NextPage"=>[], "Relax"=>true} ]
+      ]
+
+      options.must_equal({"return"=>Activity::Right, "Read"=>1, "NextPage"=>[], "Relax"=>true})
+    end
+
+    it "runs from other Callable end" do
+      user.( [ options = { "return" => Activity::Left } ] ).must_equal [
+        user.outputs[:success].signal,
+        [ {"return"=>Activity::Left, "Read"=>1, "NextPage"=>[]} ]
+      ]
+
+      options.must_equal({"return"=>Activity::Left, "Read"=>1, "NextPage"=>[]})
+    end
+
+    #---
+    #- Callable( activity, start_at )
+    let(:with_nested_and_start_at) do
+      _blog = blog
+
+      Module.new do
+        extend Activity::Path()
+
+        task task: Operation::Callable( _blog, start_task: Blog::Next ), _blog.outputs[:success] => Track(:success)
+        task task: User::Relax
+      end
+    end
+
+    it "runs Callable from alternative start" do
+      with_nested_and_start_at.( [options = { "return" => Activity::Right }] ).
+        must_equal [
+          with_nested_and_start_at.outputs[:success].signal,
+          [ {"return"=>Activity::Right, "NextPage"=>[], "Relax"=>true} ]
+        ]
+
+      options.must_equal({"return"=>Activity::Right, "NextPage"=>[], "Relax"=>true})
+    end
+
+    #---
+    #- Callable(  activity, call: :__call__ ) { ... }
+    describe "Callable with :call option" do
+      let(:process) do
+        class Workout
+          def self.__call__((options, *args), *)
+            options[:workout]   = 9
+
+            return Activity::Right, [options, *args]
+          end
+        end
+
+        subprocess = Operation::Callable( Workout, call: :__call__ )
+
+        Module.new do
+        extend Activity::Path()
+
+          task task: subprocess
+          task task: User::Relax
+        end
+      end
+
+      it "runs Callable process with __call__" do
+        process.( [options = { "return" => Activity::Right }] ).
+          must_equal [
+            process.outputs[:success].signal,
+            [{"return"=>Activity::Right, :workout=>9, "Relax"=>true}]
+          ]
+
+        options.must_equal({"return"=>Activity::Right, :workout=>9, "Relax"=>true})
+      end
+    end
+  end
+end