trailblazer-activity 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c710a0a76320ef3d041b5abeff53c24b34b1923caff08e3c92656919af62431
-  data.tar.gz: b235c975eff4e9174110270e73c75e56ec3d10fd3038616039a5de27322043d3
+  metadata.gz: f042c2ed7dab6bafd3932cfbc357ada176de13aed6a91ba05be74f0d9d000ede
+  data.tar.gz: 471066060ff8ad800f77e26e0f1cc7090ff1b0a8820971c41de93f1760a6cf74
 SHA512:
-  metadata.gz: 38bff15d697d6362b36df62be35a05248510ac6c4326962a1e12c0c3fb041da30aa39c1c6ab8c591d77cbcb186534a4284bfeba33b6cc79e4ef684ef7837e9b9
-  data.tar.gz: 586078a93ac567f69c079b017f054513e4069b8613e63badb19a0b61a8f72fbdfb22e3fb98fa8d97c233a4ee1b2818537d9e4df72d2fe0c7a2b7dcdb0b4a5bf4
+  metadata.gz: 02726f73b7af8b91ee4b34bc87dbb0a15246eb35d520ae2cd165519382d0578cad791466ff81e85ed4f95e31cf3988562115c40a6f90ab0c80b96c776c444809
+  data.tar.gz: dfb7ad6686ed5f0a8668a032c2b65357b0e5c857afa6459a9f1a101e728aa454c38cc1814133172aabbf8ee63ef350dda9c33f2997527161e566e93b1c10da44

data/.github/workflows/ci.yml

@@ -6,7 +6,7 @@ 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', 3.1, head, jruby, jruby-head]
+        ruby: [2.5, 2.6, 2.7, '3.0', 3.1, 3.2, head, jruby, jruby-head]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3

data/CHANGES.md

@@ -1,3 +1,46 @@
+# 0.15.1
+
+* Introduce `Extension.WrapStatic()` as a consistent interface for creating wrap_static extensions
+  exposing the friendly interface.
+* Deprecate `Extension(merge: ...)` since we have `Extension.WrapStatic` now.
+* Better deprecation warnings for extensions using `Insert` and not the friendly interface.
+
+# 0.15.0
+
+* Rename `Circuit::Run` to `Circuit::Runner` for consistency with `TaskWrap::Runner`.
+* Add `:flat_activity` keyword argument to `Testing.nested_activity`, so you can inject any activity for `:D`.
+  Also, allow to change `:D`'s ID with the `:d_id` option.
+* Introduce `Deprecate.warn` to have consistent deprecation warnings across all gems.
+* Introduce `Activity.call` as a top-level entry point and abstraction for `TaskWrap.invoke`.
+
+## TaskWrap
+
+* Remove the `:wrap_static` keyword argument for `TaskWrap.invoke` and replace it with `:container_activity`.
+* Make `TaskWrap.initial_wrap_static` return `INITIAL_TASK_WRAP` instead of recompiling it for every `#invoke`.
+* Introduce `TaskWrap.container_activity_for` to build "host activities" that are used to provide a wrap_static to
+  the actually run activity. This is also used in the `Each()` macro and other places.
+* Allow `append: nil` for friendly interface.
+
+  ```ruby
+  TaskWrap.Extension([method(:add_1), id: "user.add_1", append: nil])`.
+  ```
+  This appends the step to the end of the pipeline.
+
+## Introspect
+
+* Add `Introspect.find_path` to retrieve a `Graph::Node` and its hosting activity from a deeply nested graph.
+  Note that this method is still considered private.
+* Add `Introspect::TaskMap` as a slim interface for introspecting `Activity` instances. Note that `Graph` might get
+  moved to `developer` as it is very specific to rendering circuits.
+
+## TaskAdapter
+
+* Rename `Activity::TaskBuilder.Binary()` to `Activity::Circuit::TaskAdapter.for_step()`. It returns a `TaskAdapter`
+  instance, which is a bit more descriptive than a `Task` instance.
+* Add `Circuit.Step(callable_with_step_interface)` which accepts a step-interface callable and, when called, returns
+  its result and the `ctx`. This is great for deciders in macros where you don't want the step's result on the `ctx`.
+* Add `TaskWrap::Pipeline::TaskBuilder`.
+
 # 0.14.0
 
 * Remove `Pipeline.insert_before` and friends. Pipeline is now altered using ADDS mechanics, just

data/lib/trailblazer/activity/adds.rb

@@ -44,8 +44,9 @@ module Trailblazer
           end
 
           # @private
-          def self.build_adds(task, id:, prepend: "task_wrap.call_task", append: nil)
-            insert, insert_id = append ? [:Append, append] : [:Prepend, prepend]
+          def self.build_adds(task, id:, prepend: "task_wrap.call_task", append: false)
+            insert, insert_id =
+              append === false ? [:Prepend, prepend] : [:Append, append]
 
             {
               insert: [Activity::Adds::Insert.method(insert), insert_id],

data/lib/trailblazer/activity/circuit/task_adapter.rb

@@ -0,0 +1,113 @@
+module Trailblazer
+  class Activity
+    # Circuit::TaskAdapter:   Uses Circuit::Step to translate incoming, and returns a circuit-interface
+    #                 compatible return set.
+    class Circuit
+      # Create a `Circuit::Step` instance. Mostly this is used inside a `TaskAdapter`.
+      #
+      # @param    [callable_with_step_interface] Any kind of callable object or `:instance_method` that receives
+      #   a step interface.
+      # @param    [:option] If true, the user's callable argument is wrapped in `Trailblazer::Option`.
+      # @return   [Circuit::Step, Circuit::Step::Option] Returns a callable circuit-step.
+      # @see      https://trailblazer.to/2.1/docs/activity#activity-internals-step-interface
+      def self.Step(callable_with_step_interface, option: false)
+        if option
+          return Step::Option.new(Trailblazer::Option(callable_with_step_interface), callable_with_step_interface)
+        end
+
+        Step.new(callable_with_step_interface, callable_with_step_interface) # DISCUSS: maybe we can ditch this, only if performance is cool here, but where would we use that?
+      end
+
+      # {Step#call} translates the incoming circuit-interface to the step-interface,
+      # and returns the return value of the user's callable. By design, it is *not* circuit-interface compatible.
+      class Step
+        def initialize(step, user_proc, **)
+          @step            = step
+          @user_proc       = user_proc
+        end
+
+        # Translate the circuit interface to the step's step-interface. However,
+        # this only translates the calling interface, not the returning.
+        def call((ctx, flow_options), **circuit_options)
+          result = @step.(ctx, **ctx.to_hash)
+          # in an immutable environment we should return the ctx from the step.
+          return result, ctx
+        end
+
+        # In {Step::Option}, {@step} is expected to be wrapped in a {Trailblazer::Option}.
+        # To remember: when calling an Option instance, you need to pass {:keyword_arguments} explicitely,
+        # because of beautiful Ruby 2.5 and 2.6.
+        #
+        # This is often needed for "decider" chunks where the user can run either a method or a callable
+        # but you only want back the return value, not a Binary circuit-interface return set.
+        class Option < Step
+          def call((ctx, _flow_options), **circuit_options)
+            result = @step.(ctx, keyword_arguments: ctx.to_hash, **circuit_options) # circuit_options contains :exec_context.
+            # in an immutable environment we should return the ctx from the step.
+            return result, ctx
+          end
+        end
+      end
+
+      class TaskAdapter
+        # Returns a `TaskAdapter` instance always exposes the complete circuit-interface,
+        # and can be used directly in a {Circuit}.
+        #
+        # @note     This used to be called `TaskBuilder::Task`.
+        # @param    [step] Any kind of callable object or `:instance_method` that receives
+        #   a step interface.
+        # @param    [:option] If true, the user's callable argument is wrapped in `Trailblazer::Option`.
+        # @return   [TaskAdapter] a circuit-interface compatible object to use in a `Circuit`.
+        def self.for_step(step, binary: true, **options_for_step)
+          circuit_step = Circuit.Step(step, **options_for_step)
+
+          new(circuit_step)
+        end
+
+        # @param [circuit_step] Exposes a Circuit::Step.call([ctx, flow_options], **circuit_options) interface
+        def initialize(circuit_step, **)
+          @circuit_step = circuit_step
+        end
+
+        def call((ctx, flow_options), **circuit_options)
+          result, ctx = @circuit_step.([ctx, flow_options], **circuit_options)
+
+          # Return an appropriate signal which direction to go next.
+          signal = TaskAdapter.binary_signal_for(result, Activity::Right, Activity::Left)
+
+          return signal, [ctx, flow_options]
+        end
+
+        # Translates the return value of the user step into a valid signal.
+        # Note that it passes through subclasses of {Activity::Signal}.
+        def self.binary_signal_for(result, on_true, on_false)
+          if result.is_a?(Class) && result < Activity::Signal
+            result
+          else
+            result ? on_true : on_false
+          end
+        end
+
+        def inspect # TODO: make me private!
+          user_step = @circuit_step.instance_variable_get(:@user_proc) # DISCUSS: to we want Step#to_h?
+
+          %{#<Trailblazer::Activity::TaskBuilder::Task user_proc=#{Trailblazer::Activity::Introspect.render_task(user_step)}>}
+        end
+        alias_method :to_s, :inspect
+      end
+    end # Circuit
+
+    # TODO: remove when we drop compatibility.
+    module TaskBuilder
+      # @deprecated Use {Trailblazer::Activity::Circuit::TaskAdapter.for_step()} instead.
+      def self.Binary(user_proc)
+        Activity::Circuit::TaskAdapter.for_step(user_proc, option: true)
+      end
+
+      class << self
+        extend Gem::Deprecate
+        deprecate :Binary, "Trailblazer::Activity::Circuit::TaskAdapter.for_step()", 2023, 12
+      end
+    end
+  end # Activity
+end

data/lib/trailblazer/activity/circuit.rb

@@ -24,7 +24,7 @@ module Trailblazer
 
       # @param args [Array] all arguments to be passed to the task's `call`
       # @param task [callable] task to call
-      Run = ->(task, args, **circuit_options) { task.(args, **circuit_options) }
+      Runner = ->(task, args, **circuit_options) { task.(args, **circuit_options) }
 
       # Runs the circuit until we hit a stop event.
       #
@@ -37,8 +37,8 @@ module Trailblazer
       # @return [last_signal, options, flow_options, *args]
       #
       # NOTE: returned circuit_options are discarded when calling the runner.
-      def call(args, start_task: @start_task, runner: Run, **circuit_options)
-        circuit_options = circuit_options.merge( runner: runner ).freeze # TODO: set the :runner option via arguments_for_call to save the merge?
+      def call(args, start_task: @start_task, runner: Runner, **circuit_options)
+        circuit_options = circuit_options.merge(runner: runner) # TODO: set the :runner option via arguments_for_call to save the merge?
         task            = start_task
 
         loop do
@@ -49,7 +49,7 @@ module Trailblazer
           )
 
           # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
-          return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
+          return [last_signal, args] if @stop_events.include?(task)
 
           if (next_task = next_for(task, last_signal))
             task = next_task

data/lib/trailblazer/activity/deprecate.rb

@@ -0,0 +1,21 @@
+module Trailblazer
+  class Activity
+    module Deprecate
+      module_function
+
+      def warn(caller_location, message)
+        location = caller_location ? location_for(caller_location) : nil
+        warning   = [location, message].compact.join(" ")
+
+        Kernel.warn %{[Trailblazer] #{warning}\n}
+      end
+
+      def location_for(caller_location)
+        caller_location = caller_location
+        line_no         = caller_location.lineno
+
+        %{#{caller_location.absolute_path}:#{line_no}}
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/introspect.rb

@@ -1,15 +1,54 @@
 module Trailblazer
   class Activity
     # The Introspect API provides inflections for `Activity` instances.
-    # It abstracts internals about circuits and provides a convenient API to third-parties such as
-    # tracing, rendering an activity, or finding particular tasks.
+    #
+    # It abstracts internals about circuits and provides a convenient API to third-parties
+    # such as tracing, rendering an activity, or finding particular tasks.
     module Introspect
+      # A TaskMap is a way to introspect an {Activity}. It allows finding a {TaskAttributes}
+      # instance by its ID given at compile-time, or its task.
+      #
+      # It is much simpler and faster than the Graph interface that might get (re)moved.
+      def self.TaskMap(activity)
+        schema = activity.to_h
+        nodes  = schema[:nodes]
+
+        task_map_tuples =
+          nodes.collect do |node_attributes|
+            [
+              task = node_attributes[:task],
+              TaskMap::TaskAttributes(id: node_attributes[:id], task: task)
+            ]
+          end
+
+        TaskMap[task_map_tuples].freeze
+      end
+
+      class TaskMap < Hash
+        TaskAttributes = Struct.new(:id, :task) # TODO: extend at some point.
+
+        def self.TaskAttributes(id:, task:)
+          TaskMap::TaskAttributes.new(id, task).freeze
+        end
+
+        def find_by_id(id)
+          tuple = find { |task, attrs| attrs[:id] == id } or return
+          tuple[1]
+        end
+      end
+
       # TODO: order of step/fail/pass in Node would be cool to have
 
+      # TODO: Remove Graph. This is only useful to render the full
+      # circuit, which is a very specific task that could sit in `developer`,
+      # instead.
+      # Some thoughts here:
+      # * where do we need Schema.outputs? and where task.outputs?
+      #
+      #
       # @private This API is still under construction.
       class Graph
         def initialize(activity)
-          @activity = activity
           @schema   = activity.to_h or raise
           @circuit  = @schema[:circuit]
           @map      = @circuit.to_h[:map]
@@ -22,6 +61,7 @@ module Trailblazer
           find_with_block(&block)
         end
 
+        # TODO: convert to {#to_a}.
         def collect(strategy: :circuit)
           @map.keys.each_with_index.collect { |task, i| yield find_with_block { |node| node.task == task }, i }
         end
@@ -43,8 +83,15 @@ module Trailblazer
           node_for(existing)
         end
 
+        # Build a {Graph::Node} with outputs etc.
         def node_for(node_attributes)
-          Node(node_attributes.task, node_attributes.id, node_attributes.outputs, outgoings_for(node_attributes), node_attributes.data)
+          Node(
+            node_attributes.task,
+            node_attributes.id,
+            node_attributes.outputs, # [#<struct Trailblazer::Activity::Output signal=Trailblazer::Activity::Right, semantic=:success>]
+            outgoings_for(node_attributes),
+            node_attributes.data,
+          )
         end
 
         def Node(*args)
@@ -69,6 +116,26 @@ module Trailblazer
         Graph.new(*args)
       end
 
+      # @private
+      def self.find_path(activity, segments)
+        raise ArgumentError.new(%{[Trailblazer] Please pass #{activity}.to_h[:activity] into #find_path.}) unless activity.kind_of?(Trailblazer::Activity)
+
+        task_attributes           = TaskMap::TaskAttributes(id: nil, task: activity)
+        last_graph, last_activity = nil, TaskWrap.container_activity_for(activity) # needed for empty/root path
+
+        segments.each do |segment|
+          task_map              = Introspect.TaskMap(activity)
+          task, task_attributes = (task_map.find { |task, attributes| attributes[:id] == segment } or return) # DISCUSS: should we abstract these internals of {TaskMap} in {find_by_id}?
+
+          last_activity = activity
+          last_graph    = task_map
+
+          activity      = task
+        end
+
+        return task_attributes, last_activity, last_graph
+      end
+
       def self.render_task(proc)
         if proc.is_a?(Method)
 

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

@@ -4,7 +4,9 @@ class Trailblazer::Activity
       # Implementation structures
       Task = Struct.new(:circuit_task, :outputs, :extensions)
 
-      def self.Task(task, outputs, extensions=[]); Task.new(task, outputs, extensions) end
+      def self.Task(task, outputs, extensions=[])
+        Task.new(task, outputs, extensions)
+      end
     end
   end
 end

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

@@ -22,6 +22,7 @@ class Trailblazer::Activity
         nodes   = node_attributes(intermediate, implementation)
         outputs = outputs(intermediate.stop_task_ids, nodes)
         config  = config(implementation, config: config)
+
         Schema.new(circuit, outputs, nodes, config)
       end
 
@@ -50,7 +51,7 @@ class Trailblazer::Activity
       # Compute the connections for {circuit_task}.
       def self.connections_for(outs, task_outputs, implementation)
         Hash[
-          outs.collect { |required_out|
+          outs.collect { |required_out| # Intermediate::Out, it's abstract.
             [
               for_semantic(task_outputs, required_out.semantic).signal,
               implementation.fetch(required_out.target).circuit_task
@@ -60,11 +61,12 @@ class Trailblazer::Activity
       end
 
       def self.node_attributes(intermediate, implementation)
-        intermediate.wiring.collect do |task_ref, outputs| # id, Task{circuit_task, outputs}
-          task = implementation.fetch(task_ref.id)
-          data = task_ref[:data] # TODO: allow adding data from implementation.
+        intermediate.wiring.collect do |task_ref, outputs|
+          id                  = task_ref.id
+          implementation_task = implementation.fetch(id)
+          data                = task_ref[:data] # TODO: allow adding data from implementation.
 
-          NodeAttributes.new(task_ref.id, task.outputs, task.circuit_task, data)
+          NodeAttributes.new(id, implementation_task.outputs, implementation_task.circuit_task, data)
         end
       end
 

data/lib/trailblazer/activity/schema.rb

@@ -1,9 +1,11 @@
 module Trailblazer
   class Activity
-    NodeAttributes = Struct.new(:id, :outputs, :task, :data)
+    # In NodeAttributes we store data from Intermediate and Implementing compile-time.
+    # This would be lost otherwise.
+    NodeAttributes = Struct.new(:id, :outputs, :task, :data) # TODO: rename to Schema::Task::Attributes.
 
-    # Schema is primitive data structure + an invoker (usually coming from Activity etc)
     class Schema < Struct.new(:circuit, :outputs, :nodes, :config)
+      # {:nodes} is passed directly from {compile_activity}. We need to store this data here.
 
       # @!method to_h()
       #   Returns a hash containing the schema's components.

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

@@ -14,11 +14,14 @@ module Trailblazer
       # 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"] ])
+      #   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
+          Deprecate.warn caller_locations[0], "The :merge option for TaskWrap.Extension is deprecated and will be removed in 0.16.
+Please refer to https://trailblazer.to/2.1/docs/activity.html#activity-taskwrap-static and have a great day."
+
           return Extension::WrapStatic.new(extension: Extension.new(*merge))
           # TODO: remove me once we drop the pre-friendly interface.
         end
@@ -56,8 +59,8 @@ module Trailblazer
         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 !!!!!"
+          Deprecate.warn caller_locations[3], "You are using the old API for taskWrap extensions.
+Please update to the new TaskWrap.Extension() API."
 
           extension_rows.collect do |ary|
             {
@@ -67,6 +70,13 @@ Please update to the new TaskWrap.Extension() API: # FIXME !!!!!"
           end
         end
 
+        # Create extensions from the friendly interface that can alter the wrap_static
+        # of a step in an activity. The returned extensionn can be passed directly via {:extensions}
+        # to the compiler, or when using the `#step` DSL.
+        def self.WrapStatic(*inserts)
+          WrapStatic.new(extension: TaskWrap.Extension(*inserts))
+        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.

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

@@ -59,6 +59,27 @@ Please use the new TaskWrap.Extension() API: #FIXME!!!"
           TaskWrap::Extension.new(*inserts)
         end
       end # Merge
+
+      # Implements adapter for a callable in a Pipeline.
+      class TaskAdapter < Circuit::TaskAdapter
+        # Returns a {Pipeline::TaskAdapter} instance that can be used directly in a Pipeline.
+        # When `call`ed, it returns a Pipeline-interface return set.
+        #
+        # @see Circuit::TaskAdapter.for_step
+        def self.for_step(callable, **)
+          circuit_step = Circuit.Step(callable, option: false) # Since we don't have {:exec_context} in Pipeline, Option doesn't make much sense.
+
+          TaskAdapter.new(circuit_step) # return a {Pipeline::TaskAdapter}
+        end
+
+        def call(wrap_ctx, args)
+          _result, _new_wrap_ctx = @circuit_step.([wrap_ctx, args]) # For funny reasons, the Circuit::Step's call interface is compatible to the Pipeline's.
+
+          # DISCUSS: we're mutating wrap_ctx, that's the whole point of this abstraction (plus kwargs).
+
+          return wrap_ctx, args
+        end
+      end # TaskAdapter
     end
   end
 end

data/lib/trailblazer/activity/task_wrap.rb

@@ -14,14 +14,14 @@ 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.
-      # [: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?
+      # [:container_activity] the top-most "activity". This only has to look like an Activity
+      #   and exposes a #[] interface so [:wrap_static] can be read and it's compatible to {Trace}.
+      #   It is the virtual activity that "hosts" the actual {activity}.
+      def invoke(activity, args, wrap_runtime: {}, container_activity: container_activity_for(activity), **circuit_options)
         circuit_options = circuit_options.merge(
           runner:       TaskWrap::Runner,
           wrap_runtime: wrap_runtime,
-          # This {:activity} structure is currently (?) only needed in {TaskWrap.wrap_static_for}, where we
-          # access {activity[:wrap_static]} to compile the effective taskWrap.
-          activity:     {wrap_static: {activity => wrap_static}, nodes: {}}, # for Runner. Ideally we'd have a list of all static_wraps here (even nested).
+          activity:     container_activity, # for Runner. Ideally we'd have a list of all static_wraps here (even nested).
         )
 
         # signal, (ctx, flow), circuit_options =
@@ -31,14 +31,27 @@ module Trailblazer
       # {:extension} API
       # Extend the static taskWrap from a macro or DSL call.
       # Gets executed in {Intermediate.call} which also provides {config}.
+      def initial_wrap_static
+        INITIAL_WRAP_STATIC
+      end
 
-      def initial_wrap_static(*)
-        Pipeline.new([Pipeline.Row("task_wrap.call_task", TaskWrap.method(:call_task))])
+      # This is the top-most "activity" that hosts the actual activity being run.
+      # The data structure is used in {TaskWrap.wrap_static_for}, where we
+      # access {activity[:wrap_static]} to compile the effective taskWrap.
+      #
+      # It's also needed in Trace/Introspect and mimicks the host containing the actual activity.
+      #
+      # DISCUSS: we could cache that on Strategy/Operation level.
+      #          merging the **config hash is 1/4 slower than before.
+      def container_activity_for(activity, wrap_static: initial_wrap_static, **config)
+        {
+          wrap_static:  {activity => wrap_static},
+          **config
+        }
       end
+
+      INITIAL_WRAP_STATIC = Pipeline.new([Pipeline.Row("task_wrap.call_task", TaskWrap.method(:call_task))].freeze)
     end # TaskWrap
   end
 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/extension"
+

data/lib/trailblazer/activity/testing.rb

@@ -65,7 +65,7 @@ module Trailblazer
         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?
+        def assert_invoke(activity, terminus: :success, seq: "[]", circuit_options: {}, expected_ctx_variables: {}, **ctx_variables)
           signal, (ctx, _flow_options) = TaskWrap.invoke(
             activity,
             [
@@ -94,7 +94,7 @@ module Trailblazer
           Success = Activity::End(:success)
         end
 
-        # TODO: Remove this once all it's references are removed
+        # TODO: Remove this once all its references are removed
         def implementing
           Implementing
         end
@@ -127,14 +127,13 @@ module Trailblazer
           @_flat_activity = Activity.new(schema)
         end
 
-        def nested_activity
-          return @_nested_activity if defined?(@_nested_activity)
-
+# FIXME: why is this in Testing? We don't need this anywhere but in this gem.
+        def nested_activity(flat_activity: bc, d_id: :D)
           intermediate = Inter.new(
             {
               Inter::TaskRef("Start.default") => [Inter::Out(:success, :B)],
-              Inter::TaskRef(:B, more: true)  => [Inter::Out(:success, :D)],
-              Inter::TaskRef(:D) => [Inter::Out(:success, :E)],
+              Inter::TaskRef(:B, more: true)  => [Inter::Out(:success, d_id)],
+              Inter::TaskRef(d_id) => [Inter::Out(:success, :E)],
               Inter::TaskRef(:E) => [Inter::Out(:success, "End.success")],
               Inter::TaskRef("End.success", stop_event: true) => [Inter::Out(:success, nil)]
             },
@@ -145,14 +144,14 @@ module Trailblazer
           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)],                  []),
-            :D => Schema::Implementation::Task(c = bc, [Activity::Output(Implementing::Success, :success)],                  []),
+            d_id => Schema::Implementation::Task(flat_activity, [Activity::Output(Implementing::Success, :success)],                  []),
             :E => Schema::Implementation::Task(e = Implementing.method(:f), [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?
           }
 
           schema = Inter.(intermediate, implementation)
 
-          @_nested_activity = Activity.new(schema)
+          Activity.new(schema)
         end
 
         alias_method :bc, :flat_activity

data/lib/trailblazer/activity/version.rb

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

data/lib/trailblazer/activity.rb

@@ -10,7 +10,7 @@ module Trailblazer
     def call(args, **circuit_options)
       @schema[:circuit].(
         args,
-        **(circuit_options.merge(activity: self))
+        **circuit_options.merge(activity: self)
       )
     end
 
@@ -27,6 +27,12 @@ module Trailblazer
     def inspect
       %{#<Trailblazer::Activity:0x#{object_id}>}
     end
+
+    # Canonical entry-point to invoke an {Activity} or Strategy such as {Activity::Railway}
+    # with its taskWrap.
+    def self.call(activity, ctx)
+      TaskWrap.invoke(activity, [ctx, {}])
+    end
   end # Activity
 end
 
@@ -35,12 +41,16 @@ require "trailblazer/activity/schema"
 require "trailblazer/activity/schema/implementation"
 require "trailblazer/activity/schema/intermediate"
 require "trailblazer/activity/circuit"
+require "trailblazer/activity/circuit/task_adapter"
 require "trailblazer/activity/config"
 require "trailblazer/activity/introspect"
+require "trailblazer/activity/task_wrap/pipeline"
+require "trailblazer/activity/task_wrap/call_task"
 require "trailblazer/activity/task_wrap"
+require "trailblazer/activity/task_wrap/runner"
+require "trailblazer/activity/task_wrap/extension"
 require "trailblazer/activity/adds"
-require "trailblazer/activity/task_builder"
-
+require "trailblazer/activity/deprecate"
 require "trailblazer/option"
 require "trailblazer/context"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-22 00:00:00.000000000 Z
+date: 2023-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trailblazer-context
@@ -128,13 +128,14 @@ files:
 - lib/trailblazer/activity.rb
 - lib/trailblazer/activity/adds.rb
 - lib/trailblazer/activity/circuit.rb
+- lib/trailblazer/activity/circuit/task_adapter.rb
 - lib/trailblazer/activity/config.rb
+- lib/trailblazer/activity/deprecate.rb
 - lib/trailblazer/activity/introspect.rb
 - lib/trailblazer/activity/schema.rb
 - lib/trailblazer/activity/schema/implementation.rb
 - lib/trailblazer/activity/schema/intermediate.rb
 - lib/trailblazer/activity/structures.rb
-- 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/extension.rb

data/lib/trailblazer/activity/task_builder.rb

@@ -1,53 +0,0 @@
-module Trailblazer
-  module Activity::TaskBuilder
-    # 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 signal binary: true=>Right, false=>Left.
-    # Passes through all subclasses of Direction.~~~~~~~~~~~~~~~~~
-    def self.Binary(user_proc)
-      Task.new(Trailblazer::Option(user_proc), user_proc)
-    end
-
-    # Translates the return value of the user step into a valid signal.
-    # Note that it passes through subclasses of {Signal}.
-    def self.binary_signal_for(result, on_true, on_false)
-      if result.is_a?(Class) && result < Activity::Signal
-        result
-      else
-        result ? on_true : on_false
-      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)
-        # Execute the user step with TRB's kw args.
-        # {@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)
-
-        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
-      alias_method :to_s, :inspect
-    end
-  end
-end