trailblazer-activity-dsl-linear 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d539047d4fc798ef33f6a128457db0197bbc196f6a03ea9a49e577c338224a8e
+  data.tar.gz: 6c461ee1e7f77eb07b428d34f5a0a6689ecc5584ea25c519e434c898b4dd9ed5
+SHA512:
+  metadata.gz: 6b29289e1248383a8a10a7d81428eb729dfaeeea2e6b6bc7a400d8aa399eff1875686042ef4c27dff715cae8f9a65933da9981d9adf089d0648497b58454c404
+  data.tar.gz: 942c8edbe8e4cc5710a9fdbea07e1714c25c3027d657c84836bb844febb79c16082ca63a1d6b5c802914f1be99353daa229f2a2d09fc9e45bac263dc9d3477b0

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.1.0
+
+* This code is extracted, refactored and heavy-metaly simplified from the original `trailblazer-activity` gem.

data/DSL_IDEAS

@@ -0,0 +1,91 @@
+
+
+step a + b, Left => c           # split
+# OR
+step a, Right => b, Left => c   # split
+
+step b + b2 + b3 + d    # path
+step c + c2 + d
+step d
+
+# Introspect adds Start and end?
+
+
+step a + b + c + d # long path
+step b, Left => b  # loop
+
+# railway
+step a + b + c
+
+
+start set_model + decide, A => stripe, B => int1, C => int2
+  path stripe + send_invoice, Left =>
+
+
+railway model, build, validate, persist
+railway model, build, validate, Fail(log), persist, Fail(log_again),
+
+end(End.failure)
+end(End.success)
+path(a, decider,
+  {
+    A => railway(charge, invoice, {Left=>"End.failure", Right=>"End.success"}),
+    B => railway(int1, int_invoice, {Left=>"End.failure", Right=>"End.success"})
+    C => railway(int2, Right=>"int_invoice", {Left=>"End.failure", Right=>"End.success"})
+  }
+)
+
+path(charge =>{Left=>fail), invoice=>{Left=>fail})
+
+
+
+magnetic_to: [*]
+on:          Track(*)
+
+Path(
+  {a, :a, R+L-}
+  {b, :b, R+L-}
+  {c, :c, R+L-}, -=>a
+)
+
+Path(
+  +{a, :a, R+L-},       +=>b,  -=>b
+  +{b, :b, R+L-}        +=>c,  -=>c
+  +{c, :c, R+L-}, -=>a  +=>ES, -=>a
+  +{ES, :ES, }
+)
+
+
+
+# intermediate, e.g. from editor:
+# allows {:replace} and {:implement}, wires correct signals
+# to outgoing connections by semantic
+A{ +-} => {+=>B, -=>B}
+B{ +-} => {+=>C, -=>C}
+C{ +-} => {+=>ES, -=>A}
+ES{}
+
+=> circuit
+
+
+
+
+Path(
+  {a, :a, R+L-},       +=>b,  -=>b
+  {b, :b, R+L-}        +=>c,  -=>c
+  {c, :c, R+L-}, -=>a  +=>ES, -=>a
+  {ES, :ES, }
+)
+
+
+
+
+task [A, id: :a], [B, id: b], [C, id: c, outputs: {..}]
+
+
+
+circuit(
+  A,
+  B,
+  C=>{..}
+)

data/Gemfile

@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in workflow.gemspec
+gemspec
+
+gem "minitest-line"
+
+gem "rubocop", require: false
+
+# gem "trailblazer-context", path: "../trailblazer-context"
+# gem "trailblazer-developer", path: "../trailblazer-developer"
+gem "trailblazer-developer", github: "trailblazer/trailblazer-developer", branch: "exception-tracing"
+gem "trailblazer-activity", path: "../trailblazer-activity"

data/README.md

@@ -0,0 +1,23 @@
+# Trailblazer-Activity-DSL-Linear
+
+_The popular Railway/Fasttrack DSL for building activities._
+
+
+# Overview
+
+This gem allows creating activities by leveraging a handy DSL. Built-in are the strategies `Path`, the popular `Railway` and `FastTrack`. The latter is used for `Trailblazer::Operation`.
+
+Note that you don't need to use the DSL. You can simply create a InIm structure yourself, or use our online editor.
+
+Full documentation can be found here: trailblazer.to/2.1/#dsl-linear
+
+## Normalizer
+
+Normalizers are itself linear activities (or "pipelines") that compute all options necessary for `DSL.insert_task`.
+For example, `FailFast.normalizer` will process your options such as `fast_track: true` and add necessary connections and outputs.
+
+The different "step types" (think of `step`, `fail`, and `pass`) are again implemented as different normalizers that "inherit" generic steps.
+
+
+`:sequence_insert`
+`:connections` are callables to find the connecting tasks

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["**/*_test.rb"]
+end
+
+RuboCop::RakeTask.new
+
+task :default => :test

data/lib/trailblazer-activity-dsl-linear.rb

@@ -0,0 +1,2 @@
+require "trailblazer/activity/dsl/linear/version"
+require "trailblazer/activity/dsl/linear"

data/lib/trailblazer/activity/dsl/linear.rb

@@ -0,0 +1,163 @@
+class Trailblazer::Activity
+  module DSL
+    # Implementing a specific DSL, simplified version of the {Magnetic DSL} from 2017.
+    #
+    # Produces {Implementation} and {Intermediate}.
+    module Linear
+      module_function
+
+      # {Sequence} consists of rows.
+      # {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
+      class Sequence < Array
+        # Return {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
+        def self.create_row(task:, magnetic_to:, wirings:, **options)
+          [
+            magnetic_to,
+            task,
+            wirings,
+            options # {id: "Start.success"}
+          ]
+        end
+
+        # @returns Sequence New sequence instance
+        # TODO: name it {apply_adds or something}
+        def self.insert_row(sequence, row:, insert:)
+          insert_function, *args = insert
+
+          insert_function.(sequence, [row], *args)
+        end
+
+        def self.apply_adds(sequence, adds)
+          adds.each do |add|
+            sequence = insert_row(sequence, **add)
+          end
+
+          sequence
+        end
+
+        class IndexError < IndexError; end
+      end
+
+      # Sequence
+      module Search
+        module_function
+
+        # From this task onwards, find the next task that's "magnetic to" {target_color}.
+        # Note that we only go forward, no back-references are done here.
+        def Forward(output, target_color)
+          ->(sequence, me) do
+            target_seq_row = sequence[sequence.index(me)+1..-1].find { |seq_row| seq_row[0] == target_color }
+
+            return output, target_seq_row
+          end
+        end
+
+        def Noop(output)
+          ->(sequence, me) do
+            return output, [nil,nil,nil,{}] # FIXME
+          end
+        end
+
+        # Find the seq_row with {id} and connect the current node to it.
+        def ById(output, id)
+          ->(sequence, me) do
+            index          = Insert.find_index(sequence, id) or return output, sequence[0] # FIXME # or raise "Couldn't find {#{id}}"
+            target_seq_row = sequence[index]
+
+            return output, target_seq_row
+          end
+        end
+      end # Search
+
+      # Sequence
+      # Functions to mutate the Sequence by inserting, replacing, or deleting tasks.
+      # These functions are called in {insert_task}
+      module Insert
+        module_function
+
+        # Append {new_row} after {insert_id}.
+        def Append(sequence, new_rows, insert_id)
+          index, sequence = find(sequence, insert_id)
+
+          sequence.insert(index+1, *new_rows)
+        end
+
+        # Insert {new_rows} before {insert_id}.
+        def Prepend(sequence, new_rows, insert_id)
+          index, sequence = find(sequence, insert_id)
+
+          sequence.insert(index, *new_rows)
+        end
+
+        def Replace(sequence, new_rows, insert_id)
+          index, sequence = find(sequence, insert_id)
+
+          sequence[index], _ = *new_rows # TODO: replace and insert remaining, if any.
+          sequence
+        end
+
+        def Delete(sequence, _, insert_id)
+          index, sequence = find(sequence, insert_id)
+
+          sequence.delete(sequence[index])
+          sequence
+        end
+
+        # @private
+        def find_index(sequence, insert_id)
+          sequence.find_index { |seq_row| seq_row[3][:id] == insert_id } # TODO: optimize id location!
+        end
+
+        def find(sequence, insert_id)
+          index = find_index(sequence, insert_id) or raise Sequence::IndexError.new(insert_id.inspect)
+
+          return index, sequence.clone # Ruby doesn't have an easy way to avoid mutating arrays :(
+        end
+      end
+
+      def Merge(old_seq, new_seq, end_id: "End.success") # DISCUSS: also Insert
+        new_seq = strip_start_and_ends(new_seq, end_id: end_id)
+
+        seq = Insert.Prepend(old_seq, new_seq, end_id)
+      end
+      def strip_start_and_ends(seq, end_id:) # TODO: introduce Merge namespace?
+        cut_off_index = end_id.nil? ? seq.size : Insert.find_index(seq, end_id) # find the "first" end.
+
+        seq[1..cut_off_index-1]
+      end
+
+      module DSL
+        module_function
+
+        # Insert the task into the sequence using the {sequence_insert} strategy.
+        # @return Sequence sequence after applied insertion
+# FIXME: DSL for strategies
+        def insert_task(sequence, sequence_insert:, **options)
+          new_row = Sequence.create_row(**options)
+
+          # {sequence_insert} is usually a function such as {Linear::Insert::Append} and its arguments.
+          seq = Sequence.insert_row(sequence, row: new_row, insert: sequence_insert)
+        end
+
+        # Add one or several rows to the {sequence}.
+        # This is usually called from DSL methods such as {step}.
+        def apply_adds_from_dsl(sequence, sequence_insert:, adds:, **options)
+          # This is the ADDS for the actual task.
+          task_add = {row: Sequence.create_row(options), insert: sequence_insert} # Linear::Insert.method(:Prepend), end_id
+
+          Sequence.apply_adds(sequence, [task_add] + adds)
+        end
+      end # DSL
+
+    end
+  end
+end
+
+require "trailblazer/activity/dsl/linear/normalizer"
+require "trailblazer/activity/dsl/linear/state"
+require "trailblazer/activity/dsl/linear/strategy"
+require "trailblazer/activity/dsl/linear/compiler"
+require "trailblazer/activity/path"
+require "trailblazer/activity/railway"
+require "trailblazer/activity/fast_track"
+require "trailblazer/activity/dsl/linear/helper" # FIXME

data/lib/trailblazer/activity/dsl/linear/compiler.rb

@@ -0,0 +1,70 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        # Compile a {Schema} by computing {implementations} and {intermediate} from a {Sequence}.
+        module Compiler
+          module_function
+
+          # Default strategy to find out what's a stop event is to inspect the TaskRef's {data[:stop_event]}.
+          def find_stop_task_ids(intermediate_wiring)
+            intermediate_wiring.collect { |task_ref, outs| task_ref.data[:stop_event] ? task_ref.id : nil }.compact
+          end
+
+          # The first task in the wiring is the default start task.
+          def find_start_task_ids(intermediate_wiring)
+            [intermediate_wiring.first.first.id]
+          end
+
+          def call(sequence, find_stops: method(:find_stop_task_ids), find_start: method(:find_start_task_ids))
+            _implementations, intermediate_wiring =
+              sequence.inject([[], []]) do |(implementations, intermediates), seq_row|
+                magnetic_to, task, connections, data = seq_row
+                id = data[:id]
+
+                # execute all {Search}s for one sequence row.
+                connections = find_connections(seq_row, connections, sequence)
+
+                # FIXME: {:extensions} should be initialized
+                implementations += [[id, Schema::Implementation::Task(task, connections.collect { |output, _| output }, data[:extensions] || []) ]]
+
+                intermediates += [
+                  [
+                    Schema::Intermediate::TaskRef(id, data),
+                    # Compute outputs.
+                    connections.collect { |output, target_id| Schema::Intermediate::Out(output.semantic, target_id) }
+                  ]
+                ]
+
+                [implementations, intermediates]
+              end
+
+            start_task_ids = find_start.(intermediate_wiring)
+            stop_task_refs = find_stops.(intermediate_wiring)
+
+            intermediate   = Schema::Intermediate.new(Hash[intermediate_wiring], stop_task_refs, start_task_ids)
+            implementation = Hash[_implementations]
+
+            Schema::Intermediate.(intermediate, implementation) # implemented in the generic {trailblazer-activity} gem.
+          end
+
+          # private
+
+          def find_connections(seq_row, strategies, sequence)
+            strategies.collect do |search|
+              output, target_seq_row = search.(sequence, seq_row) # invoke the node's "connection search" strategy.
+
+              target_seq_row = sequence[-1] if target_seq_row.nil? # connect to an End if target unknown. # DISCUSS: make this configurable, maybe?
+
+              [
+                output,                                     # implementation
+                target_seq_row[3][:id],  # intermediate   # FIXME. this sucks.
+                target_seq_row # DISCUSS: needed?
+              ]
+            end.compact
+          end
+        end # Compiler
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/helper.rb

@@ -0,0 +1,78 @@
+module Trailblazer
+  class Activity
+    module DSL::Linear # TODO: rename!
+      # @api private
+      OutputSemantic = Struct.new(:value)
+      Id             = Struct.new(:value)
+      Track          = Struct.new(:color, :adds)
+      Extension      = Struct.new(:callable) do
+        def call(*args, &block)
+          callable.(*args, &block)
+        end
+      end
+
+      # Shortcut functions for the DSL.
+      module_function
+
+      #   Output( Left, :failure )
+      #   Output( :failure ) #=> Output::Semantic
+      def Output(signal, semantic=nil)
+        return OutputSemantic.new(signal) if semantic.nil?
+
+        Activity.Output(signal, semantic)
+      end
+
+      def End(semantic)
+        Activity.End(semantic)
+      end
+
+      def end_id(_end)
+        "End.#{_end.to_h[:semantic]}" # TODO: use everywhere
+      end
+
+      def Track(color)
+        Track.new(color, []).freeze
+      end
+
+      def Id(id)
+        Id.new(id).freeze
+      end
+
+      def Path(track_color: "track_#{rand}", end_id:, **options, &block)
+        # DISCUSS: here, we use the global normalizer and don't allow injection.
+        state = Activity::Path::DSL::State.new(Activity::Path::DSL.OptionsForState(track_name: track_color, end_id: end_id, **options)) # TODO: test injecting {:normalizers}.
+
+        # seq = block.call(state) # state changes.
+        state.instance_exec(&block)
+
+        seq = state.to_h[:sequence]
+
+        seq = Linear.strip_start_and_ends(seq, end_id: nil) # don't cut off end.
+
+        # Add the path before End.success - not sure this is bullet-proof.
+        adds = seq.collect do |row|
+          {
+            row:    row,
+            insert: [Linear::Insert.method(:Prepend), "End.success"]
+          }
+        end
+
+        return Track.new(track_color, adds)
+      end
+
+      # Computes the {:outputs} options for {activity}.
+      def Subprocess(activity)
+        {
+          task:    activity,
+          outputs: Hash[activity.to_h[:outputs].collect { |output| [output.semantic, output] }]
+        }
+      end
+
+      def normalize(options, local_keys) # TODO: test me.
+        locals  = options.reject { |key, value| ! local_keys.include?(key) }
+        foreign = options.reject { |key, value| local_keys.include?(key) }
+        return foreign, locals
+      end
+    end
+  end
+end