trailblazer-activity 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b06f440b4b9b94230fad09bc1b2024ee3297d3b454cae381f01053af65dfe8d
-  data.tar.gz: 1cd2bae0d2bd7a7f18cacee0d54af07fa4e8783b75b2852816c6882bb5f17b6a
+  metadata.gz: cf0052816c7f4a1ed202128395c3c8324a27b139bbfcb163314848eaf5132d2d
+  data.tar.gz: 94f9951381191ce8f25816aa27228a17c27c7d271e246c94a8667f315ca2f885
 SHA512:
-  metadata.gz: 4844b0b023f93fc12f218932a7d574d96e94684adaab4a186f85cb378cb7e7e92b889bec061af70bc6731d83a56a0fe5ff2651f5f250a0e4d091b454304193e5
-  data.tar.gz: 3a41f612cecfabdc2e5d0fef50411f5db1a5c6867a8c88ce784e569bfcc2b17b62bfda7a4104b8bbbb68cb157c311961622e7f64b9e5cc811ff09ee1db133296
+  metadata.gz: 34b620b89186a2656671005b026f5f3f28151bcae374d058d047175553dd77b3a0c6c23557be84e03a297c9e7e02185b22ac09e4149ba843bed48db3261451a3
+  data.tar.gz: 512ac5bdb8af2ef4948c70c2292910e4d406f600c4d5a178afdfc02f8b70497f8b15e86ee297e4199ac4f3716be509986a21a7de33346418b60ce22501ab8930

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,68 @@
+# 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
+  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`.

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