trailblazer-operation 0.0.13 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c4a0c7253d802e980c74cd74a538803a76fee4a4
-  data.tar.gz: 0e44522d1373cfa7733fdc5591bad5df8b94dd57
+  metadata.gz: e11de8247c38298cb548d31fb21ca138949204da
+  data.tar.gz: fd3a2a39355bc6e064d174e098d542f69e8f0fbc
 SHA512:
-  metadata.gz: 1a6187f6f92373ed7dc908ca819ff8b72503e3dfdf72addc8aa2c3140c05a5502d241e8109482fe51e3ea34f6aaa012f3c8751df898d3eb7aac4ec62641a0a23
-  data.tar.gz: 7486af11d465c14f21506bcf48201d2b917766e9906e72c610d14f6d6598c1a498a7558f578c37f562def2cbe0b7929e6313d5714e584f63a048153be7770e90
+  metadata.gz: 2b65963cfacea4a758ee64ede04d7c67a6e84433503d0278ebf8e163509205c1a75360fad353a76a271eb2392f5bdeecba66faebe6d78438b6c9b9d1eda36834
+  data.tar.gz: e8edfcc04c39863635ee3123e90c9ea1a024240b61b54ea3356906a687c62a4929041949dad345f9e214ef104b4a6060d655d4461ecff637966d73c495e676a5

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,47 @@
+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.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,16 @@ gem "dry-auto_inject"
 
 gem "minitest-line"
 gem "benchmark-ips"
-# gem "pipetree", path: "../pipetree"
-# gem "pipetree", github: "apotonick/pipetree"
+
+# gem "trailblazer-circuit", git: "https://github.com/trailblazer/trailblazer-circuit"
+# gem "trailblazer-activity", path: "../trailblazer-activity"
+# gem "trailblazer-developer", path: "../developer"
+gem "trailblazer-developer", git: "https://github.com/trailblazer/trailblazer-developer"
+# gem "representable", path: "../representable"
+
+# gem "raise", path: "../raise"
+
+# gem "declarative", path: "../declarative"
+
+gem "trailblazer-activity", path: "../circuit"
+# gem "trailblazer-activity", git: "https://github.com/trailblazer/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,98 @@
 require "forwardable"
-require "declarative"
+
+# trailblazer-context
+require "trailblazer/option"
+require "trailblazer/context"
+require "trailblazer/container_chain"
+
+require "trailblazer/activity"
+require "trailblazer/activity/magnetic"
+require "trailblazer/activity/wrap"
+
+require "trailblazer/operation/variable_mapping"
+
+require "trailblazer/operation/public_call"      # TODO: Remove in 3.0.
 require "trailblazer/operation/skill"
-require "trailblazer/operation/pipetree"
-require "trailblazer/operation/generic"
+require "trailblazer/operation/deprecated_macro" # TODO: remove in 2.2.
+require "trailblazer/operation/result"
+require "trailblazer/operation/railway"
+
+require "trailblazer/operation/railway/task_builder"
+require "trailblazer/operation/railway/fast_track"
+require "trailblazer/operation/railway/normalizer"
+require "trailblazer/operation/task_wrap"
+require "trailblazer/operation/trace"
 
 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 ::[]= # TODO: fade out this usage.
+
+    def self.inherited(subclass)
+      super
+      subclass.initialize!
+      heritage.(subclass)
+    end
+
+    module Process
+      def initialize!
+        initialize_activity_dsl!
+        recompile_process!
+      end
+
+      # builder is stateless, it's up to you to save @adds somewhere.
+      def initialize_activity_dsl!
+        builder_options = {
+          track_end:     Railway::End::Success.new(:success, semantic: :success),
+          failure_end:   Railway::End::Failure.new(:failure, semantic: :failure),
+          pass_fast_end: Railway::End::PassFast.new(:pass_fast, semantic: :pass_fast),
+          fail_fast_end: Railway::End::FailFast.new(:fail_fast, semantic: :fail_fast),
+        }
+
+        @builder, @adds = Activity::Magnetic::Builder::FastTrack.for( Railway::Normalizer, builder_options )
+        @debug          = {}
+      end
 
-    extend Skill::Accessors        # ::[] and ::[]=
+      def recompile_process!
+        @process, @outputs = Activity::Recompile.( @adds )
+      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 outputs
+        @outputs
+      end
 
-    # we want the initializer and the ::call method.
-    include Generic                # #initialize, #call, #process.
+      include Activity::Interface
+
+      # Call the actual {Process} with the options prepared in PublicCall.
+      def __call__(args, circuit_options={})
+        @process.( args, circuit_options.merge( exec_context: new ) )
+      end
+    end
+
+    extend Process # make ::call etc. class methods on Operation.
+
+    extend Activity::Heritage::Accessor
+
+    extend Activity::DSL # #_task
+    # delegate step, pass and fail via Operation::_task to the @builder, and save results in @adds.
+    extend Activity::DSL.def_dsl! :step
+    extend Activity::DSL.def_dsl! :pass
+    extend Activity::DSL.def_dsl! :fail
+    class << self
+      alias_method :success, :pass
+      alias_method :failure, :fail
+
+      extend Forwardable # TODO: test those helpers
+      def_delegators :@builder, :Path, :Output, :End #, :task
+    end
+
+    extend PublicCall              # ::call(params, { current_user: .. })
+    extend Trace                   # ::trace
+
+
+    include Railway::TaskWrap
   end
 end
+
+require "trailblazer/operation/inspect"

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 = Operation::Railway::TaskBuilder.binary_direction_for(result, Activity::Right, Activity::Left)
+
+        return direction, [options, flow_options]
+      end
+
+      return wrapped_proc, options
+    end
+  end
+end

data/lib/trailblazer/operation/inject.rb

@@ -0,0 +1,34 @@
+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)
+        Activity::Magnetic::Builder::Path.plan do
+          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,80 @@
+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.
+
+      adds = operation.instance_variable_get(:@adds)
+      alterations = Activity::Magnetic::Builder::Finalizer.adds_to_alterations(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

data/lib/trailblazer/operation/public_call.rb

@@ -0,0 +1,62 @@
+class Trailblazer::Operation
+  module 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.
+    #
+    # @return Operation::Railway::Result binary result object
+    def call(*args)
+      ctx = PublicCall.options_for_public_call(*args)
+
+      # call the activity.
+      last_signal, (options, flow_options) = __call__( [ctx, {}] ) # Railway::call # DISCUSS: this could be ::call_with_context.
+
+      # Result is successful if the activity ended with an End event derived from Railway::End::Success.
+      Railway::Result(last_signal, options, flow_options)
+    end
+
+    private
+    # Compile a Context object to be passed into the Activity::call.
+    def self.options_for_public_call(options={}, *containers)
+      # options, *containers = Deprecations.accept_positional_options(params, options, *containers) # TODO: make this optional for "power users".
+
+      # 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
+
+    module Deprecations
+      # Merge the first argument to the public Create.() into the second.
+      #
+      # DISCUSS: this is experimental since we can never know whether the call is the old or new API.
+      #
+      # The following situations are _not_ covered here:
+      # * You're using a Hash instance as a container.
+      # * You're using more than one container.
+      #
+      # If you do so (we're assuming you know what you're doing then), please update your `call`s.
+      def self.accept_positional_options( *args )
+        if args.size == 1 && args[0].instance_of?(Hash) # new style, you're doing it right.
+          args
+        elsif args.size == 2 && args[0].instance_of?(Hash) && !args[1].instance_of?(Hash) # new style with container, you're doing it right.
+          args
+        else
+          warn "[Trailblazer] Passing two positional arguments to `Operation.( params, current_user: .. )` is deprecated. Please use one hash like `Operation.( params: params, current_user: .. )`"
+          params, options, *containers = args
+          [ options.merge("params" => params), *containers ]
+        end
+      end
+    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