trailblazer-operation 0.0.13 → 0.1.1

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::Magnetic::Builder::FastTrack::FailFast end
+    def self.pass_fast!; Activity::Magnetic::Builder::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/normalizer.rb

@@ -0,0 +1,73 @@
+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
+      def self.call(task, options, unknown_options, sequence_options)
+        wrapped_task, options =
+          if task.is_a?(::Hash) # macro.
+            [
+              task[:task],
+              task.merge(options) # Note that the user options are merged over the macro options.
+            ]
+          elsif task.is_a?(Array) # TODO remove in 2.2
+            Operation::DeprecatedMacro.( *task )
+          else # user step
+            [
+              TaskBuilder.(task),
+              { id: task }.merge(options) # default :id
+            ]
+          end
+
+        options, unknown_options = deprecate_name(options, unknown_options) # TODO remove in 2.2
+
+        raise "No :id given for #{wrapped_task}" unless options[:id]
+
+        options = defaultize(task, options) # :plus_poles
+
+
+        options, locals, sequence_options = override(task, options, sequence_options) # :override
+
+        return wrapped_task, options, unknown_options, sequence_options
+      end
+
+      # Merge user options over defaults.
+      def self.defaultize(task, options)
+        {
+          plus_poles: InitialPlusPoles(),
+        }.merge(options)
+      end
+
+      # Handle the :override option which is specific to Operation.
+      def self.override(task, options, sequence_options)
+        options, locals  = Activity::Magnetic::Builder.normalize(options, [:override])
+        sequence_options = sequence_options.merge( replace: options[:id] ) if locals[:override]
+
+        return options, locals, sequence_options
+      end
+
+      def self.InitialPlusPoles
+        Activity::Magnetic::DSL::PlusPoles.new.merge(
+          Activity.Output(Activity::Right, :success) => nil,
+          Activity.Output(Activity::Left,  :failure) => nil,
+        )
+      end
+
+      def self.deprecate_name(options, unknown_options) # TODO remove in 2.2
+        unknown_options, deprecated_options = Activity::Magnetic::Builder.normalize(unknown_options, [:name])
+
+        options = options.merge( name: deprecated_options[:name] ) if deprecated_options[:name]
+
+        options, locals = Activity::Magnetic::Builder.normalize(options, [:name])
+        if locals[:name]
+          warn "[Trailblazer] The :name option for #step, #success and #failure has been renamed to :id."
+          options = options.merge(id: locals[:name])
+        end
+        return options, unknown_options
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+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
+      class Task < Proc
+        def initialize(source_location, &block)
+          @source_location = source_location
+          super &block
+        end
+
+        def to_s
+          "<Railway::Task{#{@source_location}}>"
+        end
+
+        def inspect
+          to_s
+        end
+      end
+
+# TODO: make this class replaceable so @Mensfeld gets his own call style. :trollface:
+
+      def self.call(step, on_true=Activity::Right, on_false=Activity::Left)
+        Task.new step, &->( (options, *args), **circuit_args ) do
+          # Execute the user step with TRB's kw args.
+          result = Trailblazer::Option::KW(step).(options, **circuit_args) # circuit_args contains :exec_context.
+
+          # Return an appropriate signal which direction to go next.
+          direction = binary_direction_for(result, on_true, on_false)
+
+          [ direction, [ options, *args ], **circuit_args ]
+        end
+      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
+  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/skill.rb

@@ -1,11 +1,4 @@
-require "trailblazer/skill"
-# Dependency ("skill") management for Operation.
-# Op::[]
-# Op::[]=
-# Writing, even with an existing name, will never mutate a container.
-# Op#[]
-# Op#[]=
-# Op.(params, { "constructor" => competences })
+# Dependencies can be defined on the operation. class level
 class Trailblazer::Operation
   module Skill
     # The class-level skill container: Operation::[], ::[]=.
@@ -18,24 +11,15 @@ class Trailblazer::Operation
       extend Forwardable
       def_delegators :skills, :[], :[]=
     end
+  end
 
-    # Overrides Operation::call, creates the Skill hash and passes it to :call.
-    module Call
-      def call(options={}, *dependencies)
-        super Trailblazer::Skill.new(options, *dependencies, self.skills)
-        # DISCUSS: should this be: Trailblazer::Skill.new(runtime_options: [options, *dependencies], compiletime_options: [self.skills])
-      end
-      alias :_call :call
+  # The use of this module is not encouraged and it is only here for backward-compatibility.
+  # Instead, please pass dependencies via containers, locals, or macros into the respective steps.
+  module ClassDependencies
+    def __call__( (ctx, flow_options), **circuit_options )
+      @skills.each { |name, value| ctx[name] ||= value } # this resembles the behavior in 2.0. we didn't say we liked it.
 
-      # It really sucks that Ruby doesn't have method overloading where we could simply have
-      # two different implementations of ::call.
-      # FIXME: that shouldn't be here in this namespace.
-      module Positional
-        def call(params={}, options={}, *dependencies)
-          super(options.merge("params" => params), *dependencies)
-        end
-      end
+      super
     end
-
   end
 end

data/lib/trailblazer/operation/task_wrap.rb

@@ -0,0 +1,68 @@
+module Trailblazer
+  module Operation::Railway
+    module TaskWrap
+      def self.included(includer)
+        includer.extend ClassMethods # ::__call__, ::inititalize_task_wraps!
+        includer.extend DSL
+
+        includer.initialize_task_wraps!
+      end
+
+      module ClassMethods
+        def initialize_task_wraps!
+          heritage.record :initialize_task_wraps!
+
+          # The map of task_wrap per step/task. Note that it defaults to Wrap.initial_activity.
+          # This gets extended at compile-time for particular tasks as the steps are created via the DSL.
+          self["__static_task_wraps__"] = ::Hash.new(Activity::Wrap.initial_activity)
+        end
+
+        # __call__ prepares `flow_options` and `static_wraps` for {TaskWrap::Runner}.
+        def __call__(args, **circuit_args)
+          args, _circuit_args = TaskWrap.arguments_for_call(self, args, **circuit_args)
+
+          super( args, circuit_args.merge(_circuit_args) ) # Railway::__call__
+        end
+      end
+
+      def self.arguments_for_call(operation, (options, flow_options), **circuit_args)
+        wrap_static = operation["__static_task_wraps__"]
+
+        circuit_args = {
+          runner:        Activity::Wrap::Runner,
+                  # FIXME: this sucks, why do we even need to pass an empty runtime there?
+          wrap_runtime: circuit_args[:wrap_runtime] || ::Hash.new([]), # FIXME:this sucks. (was:) this overwrites wrap_runtime from outside.
+          wrap_static:  wrap_static,
+        }
+
+        return [ options, flow_options ], circuit_args
+      end
+
+      module DSL
+        # TODO: this override is hard to follow, we should have a pipeline circuit in DSL to add behavior.
+        # @private
+        def _task(*args)
+          returned = super # TODO: do this with a circuit :)
+          adds, (task, local_options) = returned
+
+          runner_options = local_options[:runner_options]
+
+          runner_options and apply_adds_from_runner_options!( task, runner_options )
+
+          returned
+        end
+
+        # Extend the static wrap for a specific task, at compile time.
+        def apply_adds_from_runner_options!(task, merge:raise, **ignored)
+          static_wrap = self["__static_task_wraps__"][task]
+
+          # macro might want to apply changes to the static task_wrap (e.g. Inject)
+          self["__static_task_wraps__"][task] = Activity::Magnetic::Builder.merge( static_wrap, merge )
+        end
+      end
+    end # TaskWrap
+  end
+end
+
+
+# |-- Railway::Call "insert.exec_context"

data/lib/trailblazer/operation/trace.rb

@@ -0,0 +1,49 @@
+module Trailblazer
+  class Operation
+    module Trace
+      def self.call(operation, *args)
+        ctx = PublicCall.send(:options_for_public_call, *args)
+
+        # let Activity::Trace::call handle all parameters, just make sure it calls Operation.__call__
+        call_block = ->(operation, *args) { operation.__call__(*args) }
+
+        stack, direction, options, flow_options = Activity::Trace.(
+          operation,
+          ctx,
+          &call_block # instructs Trace to use __call__.
+        )
+
+        result = Railway::Result(direction, options)
+
+        Result.new(result, stack)
+      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
+          Activity::Trace::Present.tree(@stack)
+        end
+
+        def wtf?
+          puts wtf
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/variable_mapping.rb

@@ -0,0 +1,91 @@
+class Trailblazer::Activity
+  module Wrap
+    # TaskWrap step to compute the incoming {Context} for the wrapped task.
+    # This allows renaming, filtering, hiding, of the options passed into the wrapped task.
+    #
+    # Both Input and Output are typically to be added before and after task_wrap.call_task.
+    #
+    # @note Assumption: we always have :input _and_ :output, where :input produces a Context and :output decomposes it.
+    class Input
+      def initialize(filter)
+        @filter = Trailblazer::Option(filter)
+      end
+
+      # `original_args` are the actual args passed to the wrapped task: [ [options, ..], circuit_options ]
+      #
+      def call( (wrap_ctx, original_args), **circuit_options )
+        # let user compute new ctx for the wrapped task.
+        input_ctx = apply_filter(*original_args) # FIXME: THIS SHOULD ALWAYS BE A _NEW_ Context.
+        # TODO: make this unnecessary.
+        # wrap user's hash in Context if it's not one, already (in case user used options.merge).
+        # DISCUSS: should we restrict user to .merge and options.Context?
+        input_ctx = Trailblazer.Context(input_ctx) if !input_ctx.instance_of?(Trailblazer::Context) || input_ctx==original_args[0][0]
+
+        wrap_ctx = wrap_ctx.merge( vm_original_args: original_args )
+
+        # decompose the original_args since we want to modify them.
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
+        return Trailblazer::Activity::Right, [ wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options] ]
+      end
+
+      private
+
+      def apply_filter((original_ctx, original_flow_options), original_circuit_options)
+        @filter.( original_ctx, **original_circuit_options )
+      end
+    end
+
+    # TaskWrap step to compute the outgoing {Context} from the wrapped task.
+    # This allows renaming, filtering, hiding, of the options returned from the wrapped task.
+    class Output
+      def initialize(filter, strategy=CopyMutableToOriginal)
+        @filter   = Trailblazer::Option(filter)
+        @strategy = strategy
+      end
+
+      # Runs the user filter and replaces the ctx in `wrap_ctx[:result_args]` with the filtered one.
+      def call( (wrap_ctx, original_args), **circuit_options )
+        (original_ctx, original_flow_options), original_circuit_options = original_args
+
+        returned_ctx, _ = wrap_ctx[:result_args] # this is the Context returned from `call`ing the task.
+
+        # returned_ctx is the Context object from the nested operation. In <=2.1, this might be a completely different one
+        # than "ours" we created in Input. We now need to compile a list of all added values. This is time-intensive and should
+        # be optimized by removing as many Context creations as possible (e.g. the one adding self[] stuff in Operation.__call__).
+        _, mutable_data = returned_ctx.decompose # DISCUSS: this is a weak assumption. What if the task returns a deeply nested Context?
+
+        # let user compute the output.
+        output = apply_filter(mutable_data, original_flow_options, original_circuit_options)
+
+        original_ctx = wrap_ctx[:vm_original_args][0][0]
+
+        new_ctx = @strategy.( original_ctx, output ) # here, we compute the "new" options {Context}.
+
+        wrap_ctx = wrap_ctx.merge( result_args: [new_ctx, original_flow_options] )
+
+        # and then pass on the "new" context.
+        return Trailblazer::Activity::Right, [ wrap_ctx, original_args ]
+      end
+
+      private
+
+      # @note API not stable
+      def apply_filter(mutable_data, original_flow_options, original_circuit_options)
+        @filter.(mutable_data, **original_circuit_options)
+      end
+
+      # "merge" Strategy
+      module CopyMutableToOriginal
+        # @param original Context
+        # @param options  Context The object returned from a (nested) {Activity}.
+        def self.call(original, mutable)
+          mutable.each { |k,v| original[k] = v }
+
+          original
+        end
+      end
+    end
+  end # Wrap
+end

data/lib/trailblazer/operation/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Operation
-    VERSION = "0.0.13"
+    VERSION = "0.1.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