trailblazer-activity 0.12.2 → 0.14.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64e6b7c70557dea00024b9e16b1d85ee3046589a5b759028a2178cdd6da99231
-  data.tar.gz: 2283d2744d77ca89de067f1a368c98ddc60b4e4ca39337b59066d35f642a7c65
+  metadata.gz: 5ea76d00d1fbeedcd5160134fff2223300697bd777fb58475fc8de2311c1a5ae
+  data.tar.gz: 833e2c3b9fae46af07f07a4422405e1b66606460425d39a8777b84cfed8a0518
 SHA512:
-  metadata.gz: c9a1c011210c61b7e1ae55df77d003e4029160968093b3c71c73ccd65e460bdb911a97a016b7c524f9d3806074816f195a85f8e4e66b67245f670d7c69650417
-  data.tar.gz: cc45abe8914b199fa98e31e0e6e9e9b9582e4e097c296f3407f3e365851813a632eb45133f37bf95c71212c08c15e0deafc723d952d1f00bf6e8087035bd07cd
+  metadata.gz: ff4c7f7bcd260b495348ba7286e18a60cc104d83ff176d5e82c3c80c22e23bc69cd73cb7976f3637e64b9067932651478b0538b9eaf6731ca793a31ac70e5535
+  data.tar.gz: 34c21e990a083a2a08f203f21304b0ad33ab3616450b285f7ddc4c90861c160c5c548e1ea3af92e4a4828df2f789324d21a0deb00aa1e67c07c8084654430c1f

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -6,10 +6,10 @@ jobs:
       fail-fast: false
       matrix:
         # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
-        ruby: [2.5, 2.6, 2.7, '3.0', head, jruby, jruby-head]
+        ruby: [2.5, 2.6, 2.7, '3.0', 3.1, head, jruby, jruby-head]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}

data/CHANGES.md

@@ -1,3 +1,24 @@
+# 0.14.0
+
+* Remove `Pipeline.insert_before` and friends. Pipeline is now altered using ADDS mechanics, just
+  as we do it with the `Sequence` in the `trailblazer-activity-dsl-linear` gem.
+* `Pipeline::Merge` is now `TaskWrap::Extension`. The "pre-friendly interface" you used to leverage for creating
+  taskWrap (tw) extensions is now deprecated and you will see warnings. See https://trailblazer.to/2.1/docs/activity.html#activity-taskwrap-extension
+* Replace `TaskWrap::Extension()` with `TaskWrap::Extension.WrapStatic()` as a consistent interface for creating tW extensions at compile-time.
+* Remove `Insert.find`.
+* Rename `Activity::State::Config` to `Activity::Config`.
+* Move `VariableMapping` to the `trailblazer-activity-dsl-linear` gem.
+* Move `Pipeline.prepend` to the `trailblazer-activity-linear-dsl` gem.
+* Add `Testing#assert_call` as a consistent test implementation. (0.14.0.beta2)
+
+# 0.13.0
+
+* Removed `TaskWrap::Inject::Defaults`. This is now implemented through `dsl`'s `:inject` option.
+* Removed `TaskWrap::VariableMapping.Extension`.
+* Renamed private `TaskWrap::VariableMapping.merge_for` to `.merge_instructions_for` as there's no {Merge} instance, yet.
+* Extract invocation logic in `TaskBuilder::Task` into `Task#call_option`.
+* Add `TaskWrap::Pipeline::prepend`.
+
 # 0.12.2
 
 * Use extracted `trailblazer-option`.
@@ -25,7 +46,7 @@
 
 # 0.11.2
 
-* Updrading `trailblazer-context` version :drum:
+* Upgrading `trailblazer-context` version :drum:
 
 # 0.11.1
 

data/README.md

@@ -2,15 +2,15 @@
 
 Implements Intermediate, Implementation and compiler
 
-The `activity` gem brings a light-weight DSL to define business processes, and the runtime logic to run those activities.
+The `activity` gem implements the runtime logic to invoke a new abstraction called "activities". Ideally, activities are defined using the [`dsl-linear` DSL gem](https://github.com/trailblazer/trailblazer-activity-dsl-linear).
 
 A process is a set of arbitrary pieces of logic you define, chained together and put into a meaningful context by an activity. Activity lets you focus on the implementation of steps while Trailblazer takes care of the control flow.
 
-Please find the [full documentation on the Trailblazer website](https://2019.trailblazer.to/2.1/docs/activity.html). [Note that the docs are WIP.]
+Please find the [full documentation on the Trailblazer website](https://trailblazer.to/2.1/docs/activity.html).
 
 ## Example
 
-In conjunction with [`dsl-linear`](https://github.com/trailblazer/trailblazer-activity-dsl-linear), the `activity` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example of what a railway activity could look like, along with some more complex connections (you can read more about Railway strategy in the [docs](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-railway)).
+In conjunction with [`dsl-linear`](https://github.com/trailblazer/trailblazer-activity-dsl-linear), the `activity` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example of what a railway activity could look like, along with some more complex connections (you can read more about Railway strategy in the [docs](https://trailblazer.to/2.1/docs/activity.html#activity-strategy-railway)).
 
 ```ruby
 require "trailblazer-activity"
@@ -78,15 +78,15 @@ With Activity, modeling business processes turns out to be ridiculously simple:
 
 ## Operation
 
-Trailblazer's [`Operation`](https://2019.trailblazer.to/2.1/docs/operation.html#operation-overview) internally uses an activity to model the processes.
+Trailblazer's [`Operation`](https://trailblazer.to/2.1/docs/operation.html#operation-overview) internally uses an activity to model the processes.
 
 ## Workflow
-Activities can be formed into bigger compounds and using workflow, you can build long-running processes such as a moderated blog post or a parcel delivery. Also, you don't have to use the DSL but can use the [`editor`](https://2019.trailblazer.to/2.1/docs/pro.html#pro-editor)instead(cool for more complex, long-running flows). Here comes a sample screenshot.
+Activities can be formed into bigger compounds and using workflow, you can build long-running processes such as a moderated blog post or a parcel delivery. Also, you don't have to use the DSL but can use the [`editor`](https://trailblazer.to/2.1/docs/pro.html#pro-editor)instead(cool for more complex, long-running flows). Here comes a sample screenshot.
 
-<img src="http://2019.trailblazer.to/2.1/dist/img/flow.png">
+<img src="http://trailblazer.to/2.1/dist/img/flow.png">
 
 ## License
 
 © Copyright 2018, Trailblazer GmbH
 
-Licensed under the LGPLv3 license. We also offer a commercial-friendly [license](https://2019.trailblazer.to/2.1/docs/pro.html#pro-license).
+Licensed under the LGPLv3 license. We also offer a commercial-friendly [license](https://trailblazer.to/2.1/docs/pro.html#pro-license).

data/lib/trailblazer/activity/adds.rb

@@ -0,0 +1,153 @@
+module Trailblazer
+  class Activity
+      # The Adds interface are mechanics to alter sequences/pipelines.
+      # "one" ADDS structure: {row: ..., insert: [Insert, "id"]}
+      #
+      # To work with the instructions provided here, the pipeline structure
+      # needs to expose {#to_a}.
+      module Adds
+        module_function
+        # @returns Sequence/Pipeline New sequence instance
+        # @private
+        def insert_row(pipeline, row:, insert:)
+          insert_function, *args = insert
+
+          insert_function.(pipeline, row, *args)
+        end
+
+        # Inserts one or more {Adds} into {pipeline}.
+        def apply_adds(pipeline, adds)
+          adds.each do |add|
+            pipeline = insert_row(pipeline, **add)
+          end
+
+          pipeline
+        end
+
+        # @param inserts Array of friendly interface insertions
+        # def call(pipeline, *inserts)
+        #   adds = build_adds_for_friendly_interface(inserts)
+
+        #   Adds.apply_adds(pipeline, adds)
+        # end
+
+        module FriendlyInterface
+          # @public
+          # @return Array of ADDS
+          #
+          # Translate a collection of friendly interface to ADDS.
+          # This is a mini-DSL, if you want.
+          def self.adds_for(inserts)
+            inserts.collect do |task, options|
+              build_adds(task, **options)
+            end
+          end
+
+          # @private
+          def self.build_adds(task, id:, prepend: "task_wrap.call_task", append: nil)
+            insert, insert_id = append ? [:Append, append] : [:Prepend, prepend]
+
+            {
+              insert: [Activity::Adds::Insert.method(insert), insert_id],
+              row:    TaskWrap::Pipeline::Row(id, task)
+            }
+          end
+        end
+
+        # Functions to alter the Sequence/Pipeline by inserting, replacing, or deleting a row.
+        #
+        # they don't mutate the data structure but rebuild it, has to respond to {to_a}
+        #
+        # These methods are invoked via {Adds.apply_adds} and should never be called directly.
+        module Insert
+          module_function
+
+          # Append {new_row} after {insert_id}.
+          def Append(pipeline, new_row, insert_id=nil)
+            build_from_ary(pipeline, insert_id) do |ary, index|
+              index = ary.size if index.nil? # append to end of pipeline.
+
+              range_before_index(ary, index+1) + [new_row] + Array(ary[index+1..-1])
+            end
+          end
+
+          # Insert {new_row} before {insert_id}.
+          def Prepend(pipeline, new_row, insert_id=nil)
+            build_from_ary(pipeline, insert_id) do |ary, index|
+              index = 0 if index.nil? # Prepend to beginning of pipeline.
+
+              range_before_index(ary, index) + [new_row] + ary[index..-1]
+            end
+          end
+
+          def Replace(pipeline, new_row, insert_id)
+            build_from_ary(pipeline, insert_id) do |ary, index|
+              range_before_index(ary, index) + [new_row] + ary[index+1..-1]
+            end
+          end
+
+          def Delete(pipeline, _, insert_id)
+            build_from_ary(pipeline, insert_id) do |ary, index|
+              range_before_index(ary, index) + ary[index+1..-1]
+            end
+          end
+
+          # @private
+          def build(sequence, rows)
+            sequence.class.new(rows)
+          end
+
+          # @private
+          def find_index(ary, insert_id)
+            ary.find_index { |row| row.id == insert_id }
+          end
+
+          # Converts the pipeline structure to an array,
+          # automatically finds the index for {insert_id},
+          # and calls the user block with the computed values.
+          #
+          # Single-entry point, could be named {#call}.
+          # @private
+          def apply_on_ary(pipeline, insert_id, raise_index_error: true, &block)
+            ary   = pipeline.to_a
+
+            if insert_id.nil?
+              index = nil
+            else
+              index = find_index(ary, insert_id) # DISCUSS: this only makes sense if there are more than {Append} using this.
+              raise IndexError.new(pipeline, insert_id) if index.nil? && raise_index_error
+            end
+
+            _new_ary = yield(ary, index) # call the block.
+          end
+
+          def build_from_ary(pipeline, insert_id, &block)
+            new_ary = apply_on_ary(pipeline, insert_id, &block)
+
+            # Wrap the sequence/pipeline array into a concrete Sequence/Pipeline.
+            build(pipeline, new_ary)
+          end
+
+          # Always returns a valid, concat-able array for all indices
+          # before the {index}.
+          # @private
+          def range_before_index(ary, index)
+            return [] if index == 0
+            ary[0..index-1]
+          end
+        end # Insert
+
+        class IndexError < ::IndexError
+          def initialize(sequence, step_id)
+            valid_ids = sequence.to_a.collect{ |row| row.id.inspect }
+
+            message = "\n" \
+              "\e[31m#{step_id.inspect} is not a valid step ID. Did you mean any of these ?\e[0m\n" \
+              "\e[32m#{valid_ids.join("\n")}\e[0m"
+
+            super(message)
+          end
+        end
+      end
+  end
+end

data/lib/trailblazer/activity/circuit.rb

@@ -76,13 +76,10 @@ module Trailblazer
         outputs[signal]
       end
 
-      # Common reasons to raise IllegalSignalError are
-      #   * Returning invalid signal from custom Macros
-      #   * Returning invalid signal from steps which are not taskWrapped, for example: `step task: method(:validate)`
-      #
-      # Rest assured, it won't be raised in case of below scenarios where they can return any value,
-      #   * Steps with instance method signature, for example, `step :load_user`
-      #   * Steps with proc signature, for example `step ->(ctx, **){}`
+      # Common reasons to raise IllegalSignalError are when returning signals from
+      #   * macros which are not registered
+      #   * subprocesses where parent process have not registered that signal
+      #   * ciruit interface steps, for example: `step task: method(:validate)`
       class IllegalSignalError < RuntimeError
         attr_reader :task, :signal
 
@@ -90,9 +87,9 @@ module Trailblazer
           @task = task
           @signal = signal
 
-          message = "#{exec_context.class}: \n\t" \
-            "\sUnrecognized Signal `#{signal.inspect}` returned from #{task.inspect}. Registered signals are, \n" \
-            "- #{outputs.keys.join("\n- ")}"
+          message = "#{exec_context.class}: \n" \
+            "\e[31mUnrecognized Signal `#{signal.inspect}` returned from #{task.inspect}. Registered signals are, \e[0m\n" \
+            "\e[32m#{outputs.keys.map(&:inspect).join("\n")}\e[0m"
 
           super(message)
         end

data/lib/trailblazer/activity/config.rb

@@ -1,33 +1,32 @@
 module Trailblazer
-  module Activity::State
-    # Compile-time
-    #
-    # DISCUSS: we could replace parts with Hamster::Hash.
+  class Activity
+    # Config API allows you to read and write immutably to the activity's
+    # {:config} field. Most of the times, this only contains {:wrap_static}.
     module Config
       module_function
 
-      def set(state, *args)
+      def set(config, *args)
         if args.size == 2
           key, value = *args
 
-          state = state.merge(key => value)
+          config = config.merge(key => value)
         else
           directive, key, value = *args
 
-          state = state.merge( directive => {}.freeze ) unless state.key?(directive)
+          config = config.merge( directive => {}.freeze ) unless config.key?(directive)
 
-          directive_hash = state[directive].merge(key => value)
-          state = state.merge( directive => directive_hash.freeze )
+          directive_hash = config[directive].merge(key => value)
+          config = config.merge( directive => directive_hash.freeze )
         end
 
-        state
+        config
       end
 
-      def get(state, *args)
+      def get(config, *args)
         directive, key = *args
 
-        return state[directive] if args.size == 1
-        return state[directive][key] if state.key?(directive)
+        return config[directive] if args.size == 1
+        return config[directive][key] if config.key?(directive)
 
         nil
       end

data/lib/trailblazer/activity/schema/intermediate.rb

@@ -76,7 +76,8 @@ class Trailblazer::Activity
         end.flatten(1)
       end
 
-      # Invoke each task's extensions (usually coming from the DSL or some macro).
+      # Invoke each task's extensions (usually coming from the DSL user or some macro).
+      # We're expecting each {ext} to be a {TaskWrap::Extension::WrapStatic} instance.
       def self.config(implementation, config:)
         implementation.each do |id, task|
           task.extensions.each { |ext| config = ext.(config: config, id: id, task: task) } # DISCUSS: ext must return new {Config}.

data/lib/trailblazer/activity/schema.rb

@@ -11,5 +11,3 @@ module Trailblazer
     end # Schema
   end
 end
-require "trailblazer/activity/schema/implementation"
-require "trailblazer/activity/schema/intermediate"

data/lib/trailblazer/activity/task_builder.rb

@@ -18,17 +18,20 @@ module Trailblazer
       end
     end
 
+    # Wraps a {task} (that usually expects the task interface) into a circuit interface
+    # that can be used directly in a {Circuit}.
+    # We expect {task} to be exposing an {Option()} interface when calling it.
     class Task
       def initialize(task, user_proc)
         @task            = task
         @user_proc       = user_proc
-
         freeze
       end
 
-      def call( (ctx, flow_options), **circuit_options )
+      def call((ctx, flow_options), **circuit_options)
         # Execute the user step with TRB's kw args.
-        result = @task.(ctx, keyword_arguments: ctx.to_hash, **circuit_options) # circuit_options contains :exec_context.
+        # {@task} is/implements {Trailblazer::Option} interface.
+        result = call_option(@task, [ctx, flow_options], **circuit_options)
 
         # Return an appropriate signal which direction to go next.
         signal = Activity::TaskBuilder.binary_signal_for(result, Activity::Right, Activity::Left)
@@ -36,6 +39,11 @@ module Trailblazer
         return signal, [ctx, flow_options]
       end
 
+      # Invoke the original {user_proc} that is wrapped in an {Option()}.
+      private def call_option(task_with_option_interface, (ctx, _flow_options), **circuit_options)
+        task_with_option_interface.(ctx, keyword_arguments: ctx.to_hash, **circuit_options) # circuit_options contains :exec_context.
+      end
+
       def inspect # TODO: make me private!
         %{#<Trailblazer::Activity::TaskBuilder::Task user_proc=#{Trailblazer::Activity::Introspect.render_task(@user_proc)}>}
       end

data/lib/trailblazer/activity/task_wrap/extension.rb

@@ -0,0 +1,90 @@
+module Trailblazer
+  class Activity
+    #
+    # Example with tracing:
+    #
+    # Call the task_wrap circuit:
+    #   |-- Start
+    #   |-- Trace.capture_args   [optional]
+    #   |-- Call (call actual task) id: "task_wrap.call_task"
+    #   |-- Trace.capture_return [optional]
+    #   |-- Wrap::End
+    module TaskWrap      
+      # inserts must be
+      # An {Extension} can be used for {:wrap_runtime}. It expects a collection of
+      # "friendly interface" arrays.
+      #
+      #   TaskWrap.Extension([ [task, id: "my_logger", append: "task_wrap.call_task"] ])
+      #
+      # If you want a {wrap_static} extension, wrap it using `Extension.WrapStatic.new`.
+      def self.Extension(*inserts, merge: nil)
+        if merge
+          return Extension::WrapStatic.new(extension: Extension.new(*merge))
+          # TODO: remove me once we drop the pre-friendly interface.
+        end
+
+        Extension.build(*inserts)
+      end
+
+      # An {Extension} is a collection of ADDS objects to be inserted into a taskWrap.
+      # It gets called either at
+      #   * compile-time and adds its steps to the wrap_static (see Extension::WrapStatic)
+      #   * run-time in {TaskWrap::Runner} and adds its steps dynamically at runtime to the
+      #     step's taskWrap
+      class Extension
+        # Build a taskWrap extension from the "friendly interface" {[task, id:, ...]}
+        def self.build(*inserts)
+          # For performance reasons we're computing the ADDS here and not in {#call}.
+          extension_rows = Activity::Adds::FriendlyInterface.adds_for(inserts)
+
+          new(*extension_rows)
+        end
+
+        def initialize(*extension_rows)
+          extension_rows = deprecated_extension_for(extension_rows) # TODO: remove me soon!
+
+          @extension_rows = extension_rows # those rows are simple ADDS instructions.
+        end
+
+        # Merges {extension_rows} into the {Pipeline} instance.
+        # This is usually used in step extensions or at runtime for {wrap_runtime}.
+        def call(task_wrap_pipeline)
+          Adds.apply_adds(task_wrap_pipeline, @extension_rows)
+        end
+
+        # TODO: remove me once we drop the pre-friendly interface.
+        def deprecated_extension_for(extension_rows)
+          return extension_rows unless extension_rows.find { |ext| ext.is_a?(Array) }
+
+          warn "[Trailblazer] You are using the old API for taskWrap extensions.
+Please update to the new TaskWrap.Extension() API: # FIXME !!!!!"
+
+          extension_rows.collect do |ary|
+            {
+              insert: ary[0..1],
+              row: Pipeline.Row(*ary[2])
+            }
+          end
+        end
+
+        # Extension are used at compile-time with {wrap_static}, mostly with the {dsl} gem.
+        # {WrapStatic} extensions are called for setup through {Intermediate.config} at compile-time.
+        # Each extension alters the activity's wrap_static taskWrap.
+        class WrapStatic
+          def initialize(extension:)
+            @extension = extension
+          end
+
+          def call(config:, task:, **)
+            # Add the extension's task(s) to the activity's {wrap_static} taskWrap
+            # by using the immutable {Config} interface.
+            before_pipe = Config.get(config, :wrap_static, task.circuit_task)
+
+            Config.set(config, :wrap_static, task.circuit_task, @extension.(before_pipe))
+          end
+        end # WrapStatic
+
+      end # Extension
+    end # TaskWrap
+  end
+end

data/lib/trailblazer/activity/task_wrap/pipeline.rb

@@ -3,53 +3,62 @@ class Trailblazer::Activity
     # This "circuit" is optimized for
     #   a) merging speed at run-time, since features like tracing will be applied here.
     #   b) execution speed. Every task in the real circuit is wrapped with one of us.
+    #
+    # It doesn't come with built-in insertion mechanics (except for {Pipeline.prepend}).
+    # Please add/remove steps using the {Activity::Adds} methods.
     class Pipeline
       def initialize(sequence)
         @sequence = sequence # [[id, task], ..]
       end
 
+      # Execute the pipeline and call all its steps, passing around the {wrap_ctx}.
       def call(wrap_ctx, original_args)
         @sequence.each { |(_id, task)| wrap_ctx, original_args = task.(wrap_ctx, original_args) }
 
         return wrap_ctx, original_args
       end
 
-      attr_reader :sequence
-
-      def self.insert_before(pipe, before_id, insertion)
-        index = pipe.sequence.find_index { |(id, _)| id == before_id }
-
-        seq = pipe.sequence.dup
-
-        Pipeline.new(seq.insert(index, insertion))
+      # Comply with the Adds interface.
+      def to_a
+        @sequence
       end
 
-      def self.insert_after(pipe, after_id, insertion)
-        index = pipe.sequence.find_index { |(id, _)| id == after_id }
+      # TODO: remove me when old tW extension API is deprecated.
+      def self.method(name)
+        new_name = {
+          insert_before: :Prepend,
+          insert_after: :Append,
+          append: :Append,
+          prepend: :Prepend,
+        }.fetch(name)
 
-        seq = pipe.sequence.dup
+        warn "[Trailblazer] Using `Trailblazer::Activity::TaskWrap::Pipeline.method(:#{name})` is deprecated.
+Please use the new API: #FIXME!!!"
 
-        Pipeline.new(seq.insert(index+1, insertion))
+        Trailblazer::Activity::Adds::Insert.method(new_name)
       end
 
-      def self.append(pipe, _, insertion) # TODO: test me.
-        Pipeline.new(pipe.sequence + [insertion])
+      def self.Row(id, task)
+        Row[id, task]
       end
 
-      # Merges {extension_rows} into the {task_wrap_pipeline}.
-      # This is usually used in step extensions or at runtime for {wrap_runtime}.
-      #
-      # {Extension} API
-      class Merge # TODO: RENAME TO TaskWrap::Extension(::Merge)
-        def initialize(*extension_rows)
-          @extension_rows = extension_rows
+      class Row < Array
+        def id
+          self[0]
         end
+      end
+
+      # TODO: remove {Merge} when old tW extension API is deprecated.
+      class Merge
+        def self.new(*inserts)
+          warn "[Trailblazer] Using `Trailblazer::Activity::TaskWrap::Pipeline::Merge.new` is deprecated.
+Please use the new TaskWrap.Extension() API: #FIXME!!!"
 
-        def call(task_wrap_pipeline)
-          @extension_rows.collect { |(insert_function, target_id, row)| task_wrap_pipeline = insert_function.(task_wrap_pipeline, target_id, row) }
-          task_wrap_pipeline
+          # We can safely assume that users calling {Merge.new} are using the old tW extension API, not
+          # the "friendly API". That's why we don't go through {Extension.build}.
+          TaskWrap::Extension.new(*inserts)
         end
-      end
+      end # Merge
     end
   end
 end

data/lib/trailblazer/activity/task_wrap.rb

@@ -14,7 +14,8 @@ module Trailblazer
 
       # Compute runtime arguments necessary to execute a taskWrap per task of the activity.
       # This method is the top-level entry, called only once for the entire activity graph.
-      def invoke(activity, args, wrap_runtime: {}, wrap_static: initial_wrap_static, **circuit_options)
+      # [:wrap_static] The taskWrap used for the topmost activity/operation.
+      def invoke(activity, args, wrap_runtime: {}, wrap_static: initial_wrap_static, **circuit_options) # FIXME: why do we need this method?
         circuit_options = circuit_options.merge(
           runner:       TaskWrap::Runner,
           wrap_runtime: wrap_runtime,
@@ -24,7 +25,7 @@ module Trailblazer
         )
 
         # signal, (ctx, flow), circuit_options =
-        Runner.(activity, args, **circuit_options)
+        TaskWrap::Runner.(activity, args, **circuit_options)
       end
 
       # {:extension} API
@@ -32,28 +33,7 @@ module Trailblazer
       # Gets executed in {Intermediate.call} which also provides {config}.
 
       def initial_wrap_static(*)
-        # return initial_sequence
-        TaskWrap::Pipeline.new([["task_wrap.call_task", TaskWrap.method(:call_task)]])
-      end
-
-      # Use this in your macros if you want to extend the {taskWrap}.
-      def Extension(merge:)
-        Extension.new(merge: Pipeline::Merge.new(*merge))
-      end
-
-      class Extension
-        def initialize(merge:)
-          @merge = merge
-        end
-
-        # Compile-time:
-        # Gets called via the {Normalizer} and represents an {:extensions} item.
-        # Adds/alters the activity's {wrap_static}.
-        def call(config:, task:, **)
-          before_pipe = State::Config.get(config, :wrap_static, task.circuit_task)
-
-          State::Config.set(config, :wrap_static, task.circuit_task, @merge.(before_pipe))
-        end
+        Pipeline.new([Pipeline.Row("task_wrap.call_task", TaskWrap.method(:call_task))])
       end
     end # TaskWrap
   end
@@ -61,5 +41,4 @@ end
 require "trailblazer/activity/task_wrap/pipeline"
 require "trailblazer/activity/task_wrap/call_task"
 require "trailblazer/activity/task_wrap/runner"
-require "trailblazer/activity/task_wrap/variable_mapping"
-require "trailblazer/activity/task_wrap/inject"
+require "trailblazer/activity/task_wrap/extension"

data/lib/trailblazer/activity/testing.rb

@@ -54,6 +54,38 @@ module Trailblazer
         Schema    = Trailblazer::Activity::Schema
         TaskWrap  = Trailblazer::Activity::TaskWrap
 
+        # `:seq` is always passed into ctx.
+        # @param :seq String What the {:seq} variable in the result ctx looks like. (expected seq)
+        # @param :expected_ctx_variables Variables that are added during the call by the asserted activity.
+        def assert_call(activity, terminus: :success, seq: "[]", expected_ctx_variables: {}, **ctx_variables)
+          # Call without taskWrap!
+          signal, (ctx, _) = activity.([{seq: [], **ctx_variables}, _flow_options = {}]) # simply call the activity with the input you want to assert.
+
+          assert_call_for(signal, ctx, terminus: terminus, seq: seq, **expected_ctx_variables, **ctx_variables)
+        end
+
+        # Use {TaskWrap.invoke} to call the activity.
+        def assert_invoke(activity, terminus: :success, seq: "[]", circuit_options: {}, expected_ctx_variables: {}, **ctx_variables) # DISCUSS: only for {activity} gem?
+          signal, (ctx, _flow_options) = TaskWrap.invoke(
+            activity,
+            [
+              {seq: [], **ctx_variables},
+              {}                          # flow_options
+            ],
+            **circuit_options
+          )
+
+          assert_call_for(signal, ctx, terminus: terminus, seq: seq, **ctx_variables, **expected_ctx_variables) # DISCUSS: ordering of variables?
+        end
+
+        def assert_call_for(signal, ctx, terminus: :success, seq: "[]", **ctx_variables)
+          assert_equal signal.to_h[:semantic], terminus, "assert_call expected #{terminus} terminus, not #{signal}. Use assert_call(activity, terminus: #{signal.to_h[:semantic].inspect})"
+
+          assert_equal ctx.inspect, {seq: "%%%"}.merge(ctx_variables).inspect.sub('"%%%"', seq)
+
+          return ctx
+        end
+
         module Implementing
           extend Activity::Testing.def_tasks(:a, :b, :c, :d, :f, :g)
 
@@ -67,25 +99,27 @@ module Trailblazer
           Implementing
         end
 
-        def flat_activity
+        def flat_activity(implementing: Implementing)
           return @_flat_activity if defined?(@_flat_activity)
 
           intermediate = Inter.new(
             {
               Inter::TaskRef("Start.default")      => [Inter::Out(:success, :B)],
-              Inter::TaskRef(:B, additional: true) => [Inter::Out(:success, :C)],
+              Inter::TaskRef(:B, additional: true) => [Inter::Out(:success, :C), Inter::Out(:failure, "End.failure")],
               Inter::TaskRef(:C)                   => [Inter::Out(:success, "End.success")],
-              Inter::TaskRef("End.success", stop_event: true) => [Inter::Out(:success, nil)]
+              Inter::TaskRef("End.success", stop_event: true) => [Inter::Out(:success, nil)],
+              Inter::TaskRef("End.failure", stop_event: true) => [Inter::Out(:failure, nil)],
             },
-            ["End.success"],
+            ["End.success", "End.failure"],
             ["Start.default"], # start
           )
 
           implementation = {
             "Start.default" => Schema::Implementation::Task(st = Implementing::Start, [Activity::Output(Activity::Right, :success)],        []),
-            :B => Schema::Implementation::Task(b = Implementing.method(:b), [Activity::Output(Activity::Right, :success)],                  []),
-            :C => Schema::Implementation::Task(c = Implementing.method(:c), [Activity::Output(Activity::Right, :success)],                  []),
+            :B => Schema::Implementation::Task(b = implementing.method(:b), [Activity::Output(Activity::Right, :success), Activity::Output(Activity::Left, :failure)],                  []),
+            :C => Schema::Implementation::Task(c = implementing.method(:c), [Activity::Output(Activity::Right, :success)],                  []),
             "End.success" => Schema::Implementation::Task(_es = Implementing::Success, [Activity::Output(Implementing::Success, :success)], []), # DISCUSS: End has one Output, signal is itself?
+            "End.failure" => Schema::Implementation::Task(Implementing::Failure, [Activity::Output(Implementing::Failure, :failure)], []), # DISCUSS: End has one Output, signal is itself?
           }
 
           schema = Inter.(intermediate, implementation)

data/lib/trailblazer/activity/version.rb

@@ -1,7 +1,7 @@
 module Trailblazer
   module Version
     module Activity
-      VERSION = '0.12.2'.freeze
+      VERSION = '0.14.0.beta2'.freeze
     end
   end
 end

data/lib/trailblazer/activity.rb

@@ -14,12 +14,8 @@ module Trailblazer
       )
     end
 
-    # Reader and writer method for an Activity.
-    # The writer {dsl[:key] = "value"} exposes immutable behavior and will replace the old
-    # @state with a new, modified copy.
-    #
-    # Always use the accessors to avoid leaking state to other components
-    # due to mutable write operations.
+    # DISCUSS: we could remove this reader in the future
+    # and use {Activity.to_h[:config]}.
     def [](*key)
       @schema[:config][*key]
     end
@@ -36,10 +32,13 @@ end
 
 require "trailblazer/activity/structures"
 require "trailblazer/activity/schema"
+require "trailblazer/activity/schema/implementation"
+require "trailblazer/activity/schema/intermediate"
 require "trailblazer/activity/circuit"
 require "trailblazer/activity/config"
 require "trailblazer/activity/introspect"
 require "trailblazer/activity/task_wrap"
+require "trailblazer/activity/adds"
 require "trailblazer/activity/task_builder"
 
 require "trailblazer/option"

data/trailblazer-activity.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "minitest-line"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "trailblazer-developer", ">= 0.0.7"
+  spec.add_development_dependency "trailblazer-developer", ">= 0.0.23"
 
   spec.required_ruby_version = '>= 2.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.14.0.beta2
 platform: ruby
 authors:
 - Nick Sutterer
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-12 00:00:00.000000000 Z
+date: 2022-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trailblazer-context
@@ -100,21 +100,22 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.7
+        version: 0.0.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.7
-description:
+        version: 0.0.23
+description: 
 email:
 - apotonick@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - CHANGES.md
@@ -125,6 +126,7 @@ files:
 - Rakefile
 - lib/trailblazer-activity.rb
 - lib/trailblazer/activity.rb
+- lib/trailblazer/activity/adds.rb
 - lib/trailblazer/activity/circuit.rb
 - lib/trailblazer/activity/config.rb
 - lib/trailblazer/activity/introspect.rb
@@ -135,10 +137,9 @@ files:
 - lib/trailblazer/activity/task_builder.rb
 - lib/trailblazer/activity/task_wrap.rb
 - lib/trailblazer/activity/task_wrap/call_task.rb
-- lib/trailblazer/activity/task_wrap/inject.rb
+- lib/trailblazer/activity/task_wrap/extension.rb
 - lib/trailblazer/activity/task_wrap/pipeline.rb
 - lib/trailblazer/activity/task_wrap/runner.rb
-- lib/trailblazer/activity/task_wrap/variable_mapping.rb
 - lib/trailblazer/activity/testing.rb
 - lib/trailblazer/activity/version.rb
 - trailblazer-activity.gemspec
@@ -146,7 +147,7 @@ homepage: http://trailblazer.to
 licenses:
 - LGPL-3.0
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -157,12 +158,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.8
-signing_key:
+rubygems_version: 3.2.3
+signing_key: 
 specification_version: 4
 summary: Runtime code for Trailblazer activities.
 test_files: []

data/lib/trailblazer/activity/task_wrap/inject.rb

@@ -1,39 +0,0 @@
-class Trailblazer::Activity
-  module TaskWrap
-    # Allows to inject attributes for a task and defaults them if not.
-    # Per default, the defaulting is scoped, meaning only the task will see it.
-    module Inject
-      module Defaults
-        module_function
-
-        def Extension(defaults)
-          # Returns new ctx.
-          input  = ->((original_ctx, flow_options), circuit_options) do
-            defaulted_options = defaults_for(defaults, original_ctx)
-
-            ctx = original_ctx.merge(defaulted_options)
-
-            Trailblazer::Context(ctx, {}, flow_options[:context_options])
-          end
-
-          output = ->(new_ctx, (original_ctx, _flow_options), _circuit_options) { # FIXME: use Unscope
-            _, mutable_data = new_ctx.decompose
-
-            # we are only interested in the {mutable_data} part since the disposed part
-            # represents the injected/defaulted data.
-            original_ctx.merge(mutable_data)
-          }
-
-          VariableMapping::Extension(input, output, id: input)
-        end
-
-        # go through all defaultable options and default them if appropriate.
-        def defaults_for(defaults, original_ctx)
-          Hash[
-            defaults.collect { |k, v| [k, original_ctx[k] || v] } # FIXME: doesn't allow {false/nil} currently.
-          ]
-        end
-      end
-    end # Inject
-  end
-end

data/lib/trailblazer/activity/task_wrap/variable_mapping.rb

@@ -1,90 +0,0 @@
-class Trailblazer::Activity
-  module TaskWrap
-    # Creates taskWrap steps to map variables before and after the actual step.
-    # We hook into the Normalizer, process `:input` and `:output` directives and
-    # translate them into a {DSL::Extension}.
-    #
-    # Note that the two options are not the only way to create filters, you can use the
-    # more low-level {Scoped()} etc., too, and write your own filter logic.
-    module VariableMapping
-      # The taskWrap extension that's included into the static taskWrap for a task.
-      def self.Extension(input, output, id: input.object_id)
-        Trailblazer::Activity::TaskWrap::Extension(
-          merge: merge_for(input, output, id: id),
-        )
-      end
-
-      # DISCUSS: do we want the automatic wrapping of {input} and {output}?
-      def self.merge_for(input, output, id:) # TODO: rename
-        [
-          [TaskWrap::Pipeline.method(:insert_before), "task_wrap.call_task", ["task_wrap.input", TaskWrap::Input.new(input, id: id)]],
-          [TaskWrap::Pipeline.method(:insert_after),  "task_wrap.call_task", ["task_wrap.output", TaskWrap::Output.new(output, id: id)]],
-        ]
-      end
-    end
-
-    # 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.
-
-    # Calls your {@filter} and replaces the original ctx with your returned one.
-    class Input
-      def initialize(filter, id:)
-        @filter = filter
-        @id     = id
-      end
-
-      # {input.call()} is invoked in the circuit.
-      # `original_args` are the actual args passed to the wrapped task: [ [ctx, ..], circuit_options ]
-      #
-      def call(wrap_ctx, original_args)
-        # let user compute new ctx for the wrapped task.
-        input_ctx = apply_filter(*original_args)
-
-        # decompose the original_args since we want to modify them.
-        (original_ctx, original_flow_options), original_circuit_options = original_args
-
-        wrap_ctx = wrap_ctx.merge(@id => original_ctx) # remember the original ctx by the key {@id}.
-
-        # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
-        return wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options]
-      end
-
-      private
-
-      # Invoke the @filter callable with the original circuit interface.
-      def apply_filter((ctx, original_flow_options), original_circuit_options)
-        @filter.([ctx, original_flow_options], **original_circuit_options) # returns {new_ctx}.
-      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, id:)
-        @filter = filter
-        @id     = id
-      end
-
-      # Runs your filter and replaces the ctx in `wrap_ctx[:return_args]` with the filtered one.
-      def call(wrap_ctx, original_args)
-        (original_ctx, original_flow_options), original_circuit_options = original_args
-
-        return_args = wrap_ctx[:return_args]
-
-        returned_ctx, returned_flow_options = wrap_ctx[:return_args]  # this is the Context returned from {call}ing the wrapped user task.
-        original_ctx                        = wrap_ctx[@id]           # grab the original ctx from before which was set in the {:input} filter.
-        # let user compute the output.
-        output_ctx = @filter.(returned_ctx, [original_ctx, returned_flow_options], **original_circuit_options)
-
-        wrap_ctx = wrap_ctx.merge( return_args: [output_ctx, returned_flow_options] )
-
-        # and then pass on the "new" context.
-        return wrap_ctx, original_args
-      end
-    end
-  end # Wrap
-end