trailblazer-activity 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f042c2ed7dab6bafd3932cfbc357ada176de13aed6a91ba05be74f0d9d000ede
-  data.tar.gz: 471066060ff8ad800f77e26e0f1cc7090ff1b0a8820971c41de93f1760a6cf74
+  metadata.gz: cf0052816c7f4a1ed202128395c3c8324a27b139bbfcb163314848eaf5132d2d
+  data.tar.gz: 94f9951381191ce8f25816aa27228a17c27c7d271e246c94a8667f315ca2f885
 SHA512:
-  metadata.gz: 02726f73b7af8b91ee4b34bc87dbb0a15246eb35d520ae2cd165519382d0578cad791466ff81e85ed4f95e31cf3988562115c40a6f90ab0c80b96c776c444809
-  data.tar.gz: dfb7ad6686ed5f0a8668a032c2b65357b0e5c857afa6459a9f1a101e728aa454c38cc1814133172aabbf8ee63ef350dda9c33f2997527161e566e93b1c10da44
+  metadata.gz: 34b620b89186a2656671005b026f5f3f28151bcae374d058d047175553dd77b3a0c6c23557be84e03a297c9e7e02185b22ac09e4149ba843bed48db3261451a3
+  data.tar.gz: 512ac5bdb8af2ef4948c70c2292910e4d406f600c4d5a178afdfc02f8b70497f8b15e86ee297e4199ac4f3716be509986a21a7de33346418b60ce22501ab8930

data/CHANGES.md

@@ -1,3 +1,61 @@
+# 0.16.0
+
+* Remove `Activity#[]`. Please use `activity.to_h[:config]`.
+* Change `Activity#to_h[:nodes]`. This is now a `Schema::Nodes` "hash" that is keyed by task that
+  points to `Nodes::Attributes` data structures (a replacement for `Activity::NodeAttributes`).
+  This decision reduces logic and improves performance: it turned out that most of the time an introspect
+  lookup queries for a task, not ID.
+* Introduce `Activity::Introspect.Nodes()` as a consistent and fast interface for introspection
+  and remove `Activity::Introspect::TaskMap`.
+* Remove `Activity::NodeAttributes`.
+* Move `Introspect::Graph` to `trailblazer-developer`. It's a data structure very specific
+  to rendering, which is not a part of pure runtime behavior. `Activity::Introspect.Graph()` is now deprecated.
+* `TaskWrap.container_activity_for` now accepts `:id` for setting an ID for the containered activity to
+anything other than `nil`.
+* Re-add `:nodes` to the container activity hash as this provides a consistent way for treating all `Activity`s.
+* Remove `Activity::Config`. This immutable hash interface was used in one place, only, and can easily
+  be replaced with `config.merge()`.
+* Add `Introspect::Render`. Please consider this private.
+
+## Intermediate/Implementation
+
+* Remove `Intermediate.call`, this is now done through `Intermediate::Compiler`.
+* Introduce `Intermediate::Compiler` which is simplified and is 10% faster.
+* A terminus ("end event") in `Schema::Intermediate` no longer has outputs but an empty array. The
+  `stop_event: true` option is still required to mark the `TaskRef` as a terminus.
+* `Schema::Intermediate` now keeps a map `{<terminus ID> => :semantic}` instead of the flat termini ID list and
+  one default start event instead of an array. This looks as follows.
+
+    ```ruby
+    Schema::Intermediate.new(
+      {
+        # ...
+        Intermediate::TaskRef("End.success", stop_event: true) => [Inter::Out(:success, nil)]
+      },
+      ["End.success"],
+      [:a] # start
+    ```
+
+    Now becomes
+
+    ```ruby
+    Schema::Intermediate.new(
+      {
+        # ...
+        Intermediate::TaskRef("End.success", stop_event: true) => []
+      },
+      {"End.success" => :success},
+      :a # start
+    ```
+* In line with the change in `Intermediate`, the `Implemention` termini `Task`s now don't have outputs anymore.
+
+    ```ruby
+    implementation = {
+      # ...
+      "End.success" => Schema::Implementation::Task(Activity::End.new(semantic: :success), [], []) # No need for outputs here.
+    }
+    ```
+
 # 0.15.1
 
 * Introduce `Extension.WrapStatic()` as a consistent interface for creating wrap_static extensions

data/Gemfile

@@ -1,5 +1,6 @@
 source "https://rubygems.org"
 gemspec
 
-# gem "trailblazer-developer", path: "../trailblazer-developer"
-# gem "trailblazer-context", github: "trailblazer/trailblazer-context", branch: "ruby-3"
+# gem "trailblazer-developer",  path: "../trailblazer-developer"
+gem "benchmark-ips"
+gem "standard"

data/lib/trailblazer/activity/adds.rb

@@ -1,154 +1,157 @@
 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
+    # Developer's docs: https://trailblazer.to/2.1/docs/internals#internals-wiring-api-adds-interface
+    #
+    # 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
 
-          insert_function.(pipeline, row, *args)
+      # Inserts one or more {Adds} into {pipeline}.
+      def apply_adds(pipeline, adds)
+        adds.each do |add|
+          pipeline = insert_row(pipeline, **add)
         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
+        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
+      # @param inserts Array of friendly interface insertions
+      # def call(pipeline, *inserts)
+      #   adds = build_adds_for_friendly_interface(inserts)
 
-          # @private
-          def self.build_adds(task, id:, prepend: "task_wrap.call_task", append: false)
-            insert, insert_id =
-              append === false ? [:Prepend, prepend] : [:Append, append]
+      #   Adds.apply_adds(pipeline, adds)
+      # end
 
-            {
-              insert: [Activity::Adds::Insert.method(insert), insert_id],
-              row:    TaskWrap::Pipeline::Row(id, task)
-            }
+      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
 
-        # 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
+        # @private
+        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],
+            row:    TaskWrap::Pipeline::Row(id, task)
+          }
+        end
+      end
 
-          # 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.
+      # 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
 
-              range_before_index(ary, index+1) + [new_row] + Array(ary[index+1..-1])
-            end
+        # 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.
+        # 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
+            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
+        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
+        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 build(sequence, rows)
+          sequence.class.new(rows)
+        end
 
-          # @private
-          def find_index(ary, insert_id)
-            ary.find_index { |row| row.id == insert_id }
-          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.
+        # 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
 
-          def build_from_ary(pipeline, insert_id, &block)
-            new_ary = apply_on_ary(pipeline, insert_id, &block)
+          _new_ary = yield(ary, index) # call the block.
+        end
 
-            # Wrap the sequence/pipeline array into a concrete Sequence/Pipeline.
-            build(pipeline, new_ary)
-          end
+        def build_from_ary(pipeline, insert_id, &block)
+          new_ary = apply_on_ary(pipeline, insert_id, &block)
 
-          # 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
+          # Wrap the sequence/pipeline array into a concrete Sequence/Pipeline.
+          build(pipeline, new_ary)
+        end
 
-        class IndexError < ::IndexError
-          def initialize(sequence, step_id)
-            valid_ids = sequence.to_a.collect{ |row| row.id.inspect }
+        # 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
 
-            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"
+      class IndexError < ::IndexError
+        def initialize(sequence, step_id)
+          valid_ids = sequence.to_a.collect { |row| row.id.inspect }
 
-            super(message)
-          end
+          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/task_adapter.rb

@@ -22,8 +22,8 @@ module Trailblazer
       # 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
+          @step      = step
+          @user_proc = user_proc
         end
 
         # Translate the circuit interface to the step's step-interface. However,
@@ -91,7 +91,7 @@ module Trailblazer
         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)}>}
+          %(#<Trailblazer::Activity::TaskBuilder::Task user_proc=#{Trailblazer::Activity::Introspect.render_task(user_step)}>)
         end
         alias_method :to_s, :inspect
       end

data/lib/trailblazer/activity/circuit.rb

@@ -58,7 +58,7 @@ module Trailblazer
               task,
               signal: last_signal,
               outputs: @map[task],
-              exec_context: circuit_options[:exec_context], # passed at run-time from DSL
+              exec_context: circuit_options[:exec_context] # passed at run-time from DSL
             )
           end
         end
@@ -66,7 +66,11 @@ module Trailblazer
 
       # Returns the circuit's components.
       def to_h
-        { map: @map, end_events: @stop_events, start_task: @start_task }
+        {
+          map: @map,
+          end_events: @stop_events,
+          start_task: @start_task
+        }
       end
 
       private

data/lib/trailblazer/activity/deprecate.rb

@@ -5,16 +5,15 @@ module Trailblazer
 
       def warn(caller_location, message)
         location = caller_location ? location_for(caller_location) : nil
-        warning   = [location, message].compact.join(" ")
+        warning  = [location, message].compact.join(" ")
 
-        Kernel.warn %{[Trailblazer] #{warning}\n}
+        Kernel.warn %([Trailblazer] #{warning}\n)
       end
 
       def location_for(caller_location)
-        caller_location = caller_location
-        line_no         = caller_location.lineno
+        line_no = caller_location.lineno
 
-        %{#{caller_location.absolute_path}:#{line_no}}
+        %(#{caller_location.absolute_path}:#{line_no})
       end
     end
   end

data/lib/trailblazer/activity/introspect/render.rb

@@ -0,0 +1,53 @@
+module Trailblazer
+  class Activity
+    module Introspect
+      # @private
+      module Render
+        module_function
+
+        def call(activity, **options)
+          nodes       = Introspect.Nodes(activity)
+          circuit_map = activity.to_h[:circuit].to_h[:map]
+
+          content = nodes.collect do |task, node|
+            outgoings = circuit_map[task]
+
+            conns = outgoings.collect do |signal, target|
+              " {#{signal}} => #{inspect_with_matcher(target, **options)}"
+            end
+
+            [
+              inspect_with_matcher(node.task, **options),
+              conns.join("\n")
+            ]
+          end
+
+          content = content.join("\n")
+
+          "\n#{content}".gsub(/0x\w+/, "0x")
+        end
+
+        # If Ruby had pattern matching, this function wasn't necessary.
+        def inspect_with_matcher(task, inspect_task: method(:inspect_task), inspect_end: method(:inspect_end))
+          return inspect_task.(task) unless task.is_a?(Trailblazer::Activity::End)
+          inspect_end.(task)
+        end
+
+        def inspect_task(task)
+          task.inspect
+        end
+
+        def inspect_end(task)
+          class_name = strip(task.class)
+          options    = task.to_h
+
+          "#<#{class_name}/#{options[:semantic].inspect}>"
+        end
+
+        def strip(string)
+          string.to_s.sub("Trailblazer::Activity::", "")
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/introspect.rb

@@ -5,142 +5,49 @@ module Trailblazer
     # 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)
+      # Public entry point for {Activity} instance introspection.
+      def self.Nodes(activity, task: nil, **options)
         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
+        return Nodes.find_by_id(nodes, options[:id]) if options.key?(:id)
+        return nodes.fetch(task)                     if task
+        nodes
       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
+      module Nodes
+        # @private
+        # @return Attributes data structure
+        def self.find_by_id(nodes, id)
+          tuple = nodes.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)
-          @schema   = activity.to_h or raise
-          @circuit  = @schema[:circuit]
-          @map      = @circuit.to_h[:map]
-          @configs  = @schema[:nodes]
-        end
-
-        def find(id = nil, &block)
-          return find_by_id(id) unless block_given?
-
-          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
-
-        def stop_events
-          @circuit.to_h[:end_events]
-        end
-
-        private
-
-        def find_by_id(id)
-          node = @configs.find { |_node| _node.id == id } or return
-          node_for(node)
-        end
-
-        def find_with_block
-          existing = @configs.find { |node| yield Node(node.task, node.id, node.outputs, node.data) } or return
-
-          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, # [#<struct Trailblazer::Activity::Output signal=Trailblazer::Activity::Right, semantic=:success>]
-            outgoings_for(node_attributes),
-            node_attributes.data,
-          )
-        end
-
-        def Node(*args)
-          Node.new(*args).freeze
-        end
-
-        Node     = Struct.new(:task, :id, :outputs, :outgoings, :data)
-        Outgoing = Struct.new(:output, :task)
-
-        def outgoings_for(node)
-          outputs     = node.outputs
-          connections = @map[node.task]
-
-          connections.collect do |signal, target|
-            output = outputs.find { |out| out.signal == signal }
-            Outgoing.new(output, target)
-          end
-        end
-      end
-
-      def self.Graph(*args)
-        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)
+        raise ArgumentError.new(%([Trailblazer] Please pass #{activity}.to_h[:activity] into #find_path.)) unless activity.is_a?(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 = [nil, *segments]
 
-        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}?
+        attributes    = nil
+        last_activity = nil
+        activity      = TaskWrap.container_activity_for(activity) # needed for empty/root path
 
+        segments.each do |segment|
+          attributes    = Introspect.Nodes(activity, id: segment) or return nil
           last_activity = activity
-          last_graph    = task_map
-
-          activity      = task
+          activity      = attributes.task
         end
 
-        return task_attributes, last_activity, last_graph
+        return attributes, last_activity
       end
 
       def self.render_task(proc)
         if proc.is_a?(Method)
 
           receiver = proc.receiver
-          receiver = receiver.is_a?(Class) ? (receiver.name || "#<Class:0x>") : (receiver.name || "#<Module:0x>") #"#<Class:0x>"
+          receiver = receiver.is_a?(Class) ? (receiver.name || "#<Class:0x>") : (receiver.name || "#<Module:0x>") # "#<Class:0x>"
 
           return "#<Method: #{receiver}.#{proc.name}>"
         elsif proc.is_a?(Symbol)
@@ -149,6 +56,13 @@ module Trailblazer
 
         proc.inspect
       end
+
+      # TODO: remove with 0.1.0.
+      def self.Graph(*args)
+        Deprecate.warn caller_locations[0], %(`Trailblazer::Activity::Introspect::Graph` is deprecated. Please use `Trailblazer::Developer::Introspect.Graph`)
+
+        Trailblazer::Developer::Introspect::Graph.new(*args)
+      end
     end # Introspect
   end
 end