trailblazer-operation 0.0.13 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c4a0c7253d802e980c74cd74a538803a76fee4a4
-  data.tar.gz: 0e44522d1373cfa7733fdc5591bad5df8b94dd57
+SHA256:
+  metadata.gz: d3347429bc2a448f6f41390b5d70aea2076d32235acb78f51563fbcb8f935f8e
+  data.tar.gz: 68200b340b34a5965cd773921b8282a4eb0f0ad56ae87e1b7ad2585a362cc02a
 SHA512:
-  metadata.gz: 1a6187f6f92373ed7dc908ca819ff8b72503e3dfdf72addc8aa2c3140c05a5502d241e8109482fe51e3ea34f6aaa012f3c8751df898d3eb7aac4ec62641a0a23
-  data.tar.gz: 7486af11d465c14f21506bcf48201d2b917766e9906e72c610d14f6d6598c1a498a7558f578c37f562def2cbe0b7929e6313d5714e584f63a048153be7770e90
+  metadata.gz: 6824c50e6c8f48b587afc1e8a2f08b3b1813379c811f6b1017c6088bdd9836c445839a20cec3ac1407b33290ea5c4a1d3ee47da77854de8bfde7bf24a4230662
+  data.tar.gz: b0fb9530502238b3bfab54311c93793a4c4f028091ba72a7f9e71a3eb1f760edb077577d2e542d06d6650c392b160f464a44c6f1c7d90d79b9447e468f6935c3

data/.travis.yml

@@ -3,13 +3,15 @@ before_install:
   - gem install bundler
 matrix:
   include:
-    - rvm: 1.9.3
-      gemfile: "test/gemfiles/Gemfile.ruby-1.9"
     # - rvm: 2.0.0
     #   gemfile: "test/gemfiles/Gemfile.ruby-2.0"
     - rvm: 2.1
       gemfile: Gemfile
     - rvm: 2.2.4
       gemfile: Gemfile
-    - rvm: 2.3.1
+    - rvm: 2.3.3
       gemfile: Gemfile
+    - rvm: 2.4.0
+      gemfile: Gemfile
+    - rvm: jruby-9.1.13.0
+      env: JRUBY_OPTS="--profile.api"

data/CHANGES.md

@@ -1,3 +1,103 @@
+TODO:
+* api to add your own task.
+
+lots of work on the DSL specific parts.
+    Graph and Sequence to make it easier to wire anything.
+    macros can now add/modify the wiring, e.g. their end to the our end or the next task.
+    [ use circuit for actual step_args/initialize process, too? ]
+    You can now add an unlimited number of "your own" end events, which can then be interpreted on the outside (e.g. Endpoint)
+* Introduced the `fast_track: true` option for steps. If you were returning `Railway.fail_fast!` and the like, you now need to declare that option, e.g.
+
+        ```ruby
+        step :my_validate!, fast_track: true
+        ```
+
+params:, rest: ..
+
+
+## 0.4.1
+
+* Use `activity-0.7.1`.
+
+## 0.4.0
+
+* Use `activity-0.7.0`.
+
+## 0.3.1
+
+* Moved `VariableMapping` to the `activity` gem.
+
+## 0.3.0
+
+* Use `activity` 0.6.0.
+* Remove `Operation::__call__` in favor of one `call` that dispatches to either
+    * `call_with_public_interface` this implements the complicated public `Operation.()` semantic and will be faded out with the rise of workflow engines.
+    * `call_with_circuit_interface` is the circuit-compatible version that will be invoked on nested operations.
+
+    This might seem a bit "magical" but simplifies the interface a lot. In better languages, you could use method overloading for that, in Ruby, we have to
+    do that ourselves. This decision was made with the deprecation of `Operation.()` in mind. In the future, operations will mostly be invoked from
+    workflow engines and not directly, where the engine takes care of applying the correct interface.
+
+## 0.2.5
+
+* Minor fixes for activity 0.5.2.
+
+## 0.2.4
+
+*  Use `Activity::FastTrack` signals.
+
+## 0.2.2
+
+* Use `activity-0.4.2`.
+
+## 0.2.1
+
+* Use `activity-0.4.1`.
+
+## 0.2.0
+
+* Cleanly separate `Activity` and `Operation` responsibilities. An operation is nothing more but a class around an activity, hosting instance methods and implementing inheritance.
+
+## 0.1.4
+
+* `TaskWrap.arguments_for_call` now returns the correct `circuit_options` where the `:runner` etc.'s already merged.
+
+## 0.1.3
+
+* New taskWrap API for `activity` 0.3.2.
+
+## 0.1.2
+
+* Add @mensfeld's "Macaroni" step style for a keyword-only signature for steps.
+
+## 0.1.0
+
+inspect: failure is << and success is >>
+
+call vs __call__: it's now designed to be run in a composition where the skills stuff is done only once, and the reslt object is not necessary
+
+    FastTrack optional
+    Wrapped optional
+
+* Add `pass` and `fail` as four-character aliases for `success` and `failure`.
+* Remove `Uber::Callable` requirement and treat all non-`:symbol` steps as callable objects.
+* Remove non-kw options for steps. All steps receive keyword args now:
+
+    ```ruby
+    def model(options)
+    ```
+
+    now must have a minimal signature as follows.
+
+    ```ruby
+    def model(options, **)
+    ```
+* Remove `Operation#[]` and `Operation#[]=`. Please only change state in `options`.
+* API change for `step Macro()`: the macro's return value is now called with the low-level "Task API" signature `(direction, options, flow_options)`. You need to return `[direction, options, flow_options]`. There's a soft-deprecation warning.
+* Remove support for Ruby 1.9.3 for now. This can be re-introduced on demand.
+* Remove `pipetree` in favor of [`trailblazer-circuit`](https://github.com/trailblazer/trailblazer-circuit). This allows rich workflows and state machines in an operation.
+* Remove `uber` dependency.
+
 ## 0.0.13
 
 * Rename `Operation::New` to `:Instantiate` to avoid name clashes with `New` operations in applications.

data/Gemfile

@@ -9,5 +9,7 @@ gem "dry-auto_inject"
 
 gem "minitest-line"
 gem "benchmark-ips"
-# gem "pipetree", path: "../pipetree"
-# gem "pipetree", github: "apotonick/pipetree"
+
+# gem "trailblazer-developer", path: "../developer"
+# gem "trailblazer-developer", git: "https://github.com/trailblazer/trailblazer-developer"
+gem "trailblazer-activity", path: "../trailblazer-activity"

data/Rakefile

@@ -4,15 +4,17 @@ require "rake/testtask"
 task :default => [:test]
 
 Rake::TestTask.new(:test) do |test|
-  test.libs << 'test'
+  test.libs << "test"
   test.verbose = true
 
-  test_files = FileList['test/*_test.rb']
+  test_files = FileList["test/**/*_test.rb"]
 
-  if    RUBY_VERSION == "1.9.3"
-    test_files = test_files - %w{test/dry_container_test.rb test/2.1.0-pipetree_test.rb  test/2.0.0-pipetree_test.rb}
-  elsif RUBY_VERSION == "2.0.0"
-    test_files = test_files - %w{test/dry_container_test.rb test/2.1.0-pipetree_test.rb}
+  if RUBY_VERSION == "2.0.0"
+    # test_files = test_files - %w{test/dry_container_test.rb test/2.1.0-pipetree_test.rb}
+    test_files = test_files - %w{test/step_test.rb}      + %w{test/ruby-2.0.0/step_test.rb}
+    test_files = test_files - %w{test/operation_test.rb} + %w{test/ruby-2.0.0/operation_test.rb}
+  else
+    test_files -= FileList["test/ruby-2.0.0/*"]
   end
 
   test.test_files = test_files

data/lib/trailblazer/operation.rb

@@ -1,24 +1,91 @@
 require "forwardable"
-require "declarative"
-require "trailblazer/operation/skill"
-require "trailblazer/operation/pipetree"
-require "trailblazer/operation/generic"
+
+# trailblazer-context
+require "trailblazer/option"
+require "trailblazer/context"
+require "trailblazer/container_chain"
+
+require "trailblazer/activity"
+require "trailblazer/activity/dsl/magnetic"
+
+
+require "trailblazer/operation/callable"
+
+require "trailblazer/operation/heritage"
+require "trailblazer/operation/public_call"      # TODO: Remove in 3.0.
+require "trailblazer/operation/class_dependencies"
+require "trailblazer/operation/deprecated_macro" # TODO: remove in 2.2.
+require "trailblazer/operation/result"
+require "trailblazer/operation/railway"
+
+require "trailblazer/operation/railway/fast_track"
+require "trailblazer/operation/railway/normalizer"
+require "trailblazer/operation/trace"
+
+require "trailblazer/operation/railway/macaroni"
 
 module Trailblazer
   # The Trailblazer-style operation.
   # Note that you don't have to use our "opinionated" version with result object, skills, etc.
   class Operation
-    extend Declarative::Heritage::Inherited
-    extend Declarative::Heritage::DSL
 
-    extend Skill::Accessors        # ::[] and ::[]=
+    module FastTrackActivity
+      builder_options = {
+        track_end:     Railway::End::Success.new(semantic: :success),
+        failure_end:   Railway::End::Failure.new(semantic: :failure),
+        pass_fast_end: Railway::End::PassFast.new(semantic: :pass_fast),
+        fail_fast_end: Railway::End::FailFast.new(semantic: :fail_fast),
+      }
+
+      extend Activity::FastTrack( pipeline: Railway::Normalizer::Pipeline, builder_options: builder_options )
+    end
+
+    extend Skill::Accessors        # ::[] and ::[]= # TODO: fade out this usage.
+
+    def self.inherited(subclass)
+      super
+      subclass.initialize!
+      heritage.(subclass)
+    end
 
-    include Pipetree               # ::call, ::step, ...
-    # we want the skill dependency-mechanism.
-    extend Skill::Call             # ::call(params: {}, current_user: ..)
-    extend Skill::Call::Positional # ::call(params, options)
+    def self.initialize!
+      @activity = FastTrackActivity.clone
+    end
 
-    # we want the initializer and the ::call method.
-    include Generic                # #initialize, #call, #process.
+
+    extend Activity::Interface
+
+    module Process
+      def to_h
+        @activity.to_h.merge( activity: @activity )
+      end
+    end
+
+    extend Process # make ::call etc. class methods on Operation.
+
+    extend Heritage::Accessor
+
+    class << self
+      extend Forwardable # TODO: test those helpers
+      def_delegators :@activity, :Path, :Output, :End, :Track
+      def_delegators :@activity, :outputs
+
+      def step(task, options={}, &block); add_task!(:step, task, options, &block) end
+      def pass(task, options={}, &block); add_task!(:pass, task, options, &block) end
+      def fail(task, options={}, &block); add_task!(:fail, task, options, &block) end
+
+      alias_method :success, :pass
+      alias_method :failure, :fail
+
+      def add_task!(name, task, options, &block)
+        heritage.record(name, task, options, &block)
+        @activity.send(name, task, options, &block)
+      end
+    end
+
+    extend PublicCall              # ::call(params, { current_user: .. })
+    extend Trace                   # ::trace
   end
 end
+
+require "trailblazer/operation/inspect"

data/lib/trailblazer/operation/callable.rb

@@ -0,0 +1,42 @@
+module Trailblazer
+  class Operation
+    # Use {Callable} if you have an operation or any other callable object that does
+    # _not_ expose an {Activity interface}. For example, {Operation.call} isn't compatible
+    # with activities, hence you need to decorate it using {Callable}. The returned object
+    # exposes an {Activity interface}.
+    #
+    # @param :call [Symbol] Method name to call
+    # @param options [Hash] Hash to merge into {circuit_options}, e.g. {:start_task}.
+    #
+    # @example Create and use a Callable instance.
+    #   callable = Trailblazer::Operation::Callable( Memo::Create, call: :__call__ )
+    #   callable.( [ctx, {}] ) #=> Activity interface, ::call will invoke Memo::Create.__call__.
+    def self.Callable(*args)
+      Callable.new(*args)
+    end
+
+    # Subprocess allows to have tasks with a different call interface and start event.
+    # @param activity any object with an {Activity interface}
+    class Callable
+      include Activity::Interface
+
+      def initialize(activity, call: :call, **options)
+        @activity = activity
+        @options  = options
+        @call     = call
+      end
+
+      def call(args, **circuit_options)
+        @activity.public_send(@call, args, circuit_options.merge(@options))
+      end
+
+      extend Forwardable
+      # @private
+      def_delegators :@activity, :to_h, :debug
+
+      def to_s
+        %{#<Trailblazer::Activity::Callable activity=#{@activity}>}
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/class_dependencies.rb

@@ -0,0 +1,25 @@
+# Dependencies can be defined on the operation. class level
+class Trailblazer::Operation
+  module Skill
+    # The class-level skill container: Operation::[], ::[]=.
+    module Accessors
+      # :private:
+      def skills
+        @skills ||= {}
+      end
+
+      extend Forwardable
+      def_delegators :skills, :[], :[]=
+    end
+  end
+
+  # 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_with_circuit_interface( (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.
+
+      super
+    end
+  end
+end

data/lib/trailblazer/operation/deprecated_macro.rb

@@ -0,0 +1,19 @@
+# TODO: REMOVE IN 2.2.
+module Trailblazer
+  module Operation::DeprecatedMacro
+    # Allows old macros with the `(input, options)` signature.
+    def self.call(proc, options)
+      warn %{[Trailblazer] Macros with API (input, options) are deprecated. Please use the "Task API" signature (options, flow_options) or use a simpler Callable. (#{proc})}
+
+      wrapped_proc = ->( (options, flow_options), **circuit_options ) do
+        result = proc.(circuit_options[:exec_context], options) # run the macro, with the deprecated signature.
+
+        direction = Activity::TaskBuilder.binary_signal_for(result, Activity::Right, Activity::Left)
+
+        return direction, [options, flow_options]
+      end
+
+      options.merge( task: wrapped_proc )
+    end
+  end
+end

data/lib/trailblazer/operation/heritage.rb

@@ -0,0 +1,30 @@
+module Trailblazer
+  # This is copied from the Declarative gem. This might get removed in favor of a real heritage gem.
+  class Operation
+    class Heritage < Array
+      # Record inheritable assignments for replay in an inheriting class.
+      def record(method, *args, &block)
+        self << { method: method, args: args, block: block }
+      end
+
+      # Replay the recorded assignments on inheritor.
+      # Accepts a block that will allow processing the arguments for every recorded statement.
+      def call(inheritor, &block)
+        each { |cfg| call!(inheritor, cfg, &block) }
+      end
+
+    private
+      def call!(inheritor, cfg)
+        yield cfg if block_given? # allow messing around with recorded arguments.
+
+        inheritor.send(cfg[:method], *cfg[:args], &cfg[:block])
+      end
+
+      module Accessor
+        def heritage
+          @heritage ||= Heritage.new
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/inject.rb

@@ -0,0 +1,36 @@
+module Trailblazer
+  module Operation::Wrap
+    module Inject
+      # Returns an Alteration wirings that, when applied, inserts the {ReverseMergeDefaults} task
+      # before the {Wrap::Call} task. This is meant for macros and steps that accept a dependency
+      # injection but need a default parameter to be set if not injected.
+      # @returns ADDS
+      def self.Defaults(default_dependencies)
+        Module.new do
+          extend Activity::Path::Plan()
+
+          task ReverseMergeDefaults.new( default_dependencies ),
+            id:     "ReverseMergeDefaults#{default_dependencies}",
+            before: "task_wrap.call_task"
+        end
+      end
+
+      # @api private
+      # @returns Task
+      # @param Hash list of key/value that should be set if not already assigned/set before (or injected from the outside).
+      class ReverseMergeDefaults
+        def initialize(defaults)
+          @defaults = defaults
+        end
+
+        def call((wrap_ctx, original_args), **circuit_options)
+          ctx = original_args[0][0]
+
+          @defaults.each { |k, v| ctx[k] ||= v }
+
+          return Activity::Right, [ wrap_ctx, original_args ]
+        end
+      end
+    end # Inject
+  end
+end

data/lib/trailblazer/operation/inspect.rb

@@ -0,0 +1,79 @@
+module Trailblazer
+  # Operation-specific circuit rendering. This is optimized for a linear railway circuit.
+  #
+  # @private
+  #
+  # NOTE: this is absolutely to be considered as prototyping and acts more like a test helper ATM as
+  # Inspect is not a mission-critical part.
+  class Operation
+    def self.introspect(*args)
+      Operation::Inspect.(*args)
+    end
+  end
+
+  module Operation::Inspect
+    module_function
+
+    def call(operation, options={ style: :line })
+      # TODO: better introspection API.
+
+      alterations = Activity::Magnetic::Builder::Finalizer.adds_to_alterations(operation.to_h[:adds])
+      # DISCUSS: any other way to retrieve the Alterations?
+
+      # pp alterations
+      railway = alterations.instance_variable_get(:@groups).instance_variable_get(:@groups)[:main]
+
+      rows = railway.each_with_index.collect do |element, i|
+        magnetic_to, task, plus_poles = element.configuration
+
+        created_by =
+          if magnetic_to == [:failure]
+            :fail
+          elsif plus_poles.size > 1
+            plus_poles[0].color == plus_poles[1].color ? :pass : :step
+          else
+            :pass # this is wrong for Nested, sometimes
+          end
+
+        [ i, [ created_by, element.id ] ]
+      end
+
+      return inspect_line(rows) if options[:style] == :line
+      return inspect_rows(rows)
+    end
+
+    def inspect_func(step)
+      @inspect[step]
+    end
+
+    Operator = { :fail => "<<", :pass => ">>", :step => ">"}
+
+    def inspect_line(names)
+      string = names.collect { |i, (end_of_edge, name)| "#{Operator[end_of_edge]}#{name}" }.join(",")
+      "[#{string}]"
+    end
+
+    def inspect_rows(names)
+      string = names.collect do |i, (end_of_edge, name)|
+        operator = Operator[end_of_edge]
+
+        op = "#{operator}#{name}"
+        padding = 38
+
+        proc = if operator == "<<"
+          sprintf("%- #{padding}s", op)
+        elsif [">", ">>", "&"].include?(operator.to_s)
+          sprintf("% #{padding}s", op)
+        else
+          pad = " " * ((padding - op.length) / 2)
+          "#{pad}#{op}#{pad}"
+        end
+
+        proc = proc.gsub(" ", "=")
+
+        sprintf("%2d %s", i, proc)
+      end.join("\n")
+      "\n#{string}"
+    end
+  end
+end