trailblazer-activity-dsl-linear 0.1.0

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

@@ -0,0 +1,11 @@
+module Trailblazer
+  module Version
+    module Activity
+      module DSL
+        module Linear
+          VERSION = "0.1.0"
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/fast_track.rb

@@ -0,0 +1,163 @@
+module Trailblazer
+  class Activity
+    def self.FastTrack(options)
+      Class.new(FastTrack) do
+        initialize!(Railway::DSL::State.new(FastTrack::DSL.OptionsForState(options)))
+      end
+    end
+
+    # Implementation module that can be passed to `Activity[]`.
+    class FastTrack
+      Linear = Activity::DSL::Linear
+
+      # Signals
+      FailFast = Class.new(Signal)
+      PassFast = Class.new(Signal)
+
+      module DSL
+        module_function
+
+        def normalizer
+          step_options(Trailblazer::Activity::Railway::DSL.normalizer)
+        end
+
+        def normalizer_for_fail
+          sequence = step_options(Trailblazer::Activity::Railway::DSL.normalizer_for_fail)
+
+          Path::DSL.prepend_to_path(
+            sequence,
+
+            {
+              "fast_track.fail_fast_option_for_fail"  => method(:fail_fast_option_for_fail),
+            },
+            Linear::Insert.method(:Prepend), "path.wirings"
+          )
+        end
+
+        def normalizer_for_pass
+          sequence = step_options(Trailblazer::Activity::Railway::DSL.normalizer_for_pass)
+
+          Path::DSL.prepend_to_path(
+            sequence,
+
+            {
+              "fast_track.pass_fast_option_for_pass"  => method(:pass_fast_option_for_pass),
+            },
+            Linear::Insert.method(:Prepend), "path.wirings"
+          )
+        end
+
+        def step_options(sequence)
+          Path::DSL.prepend_to_path( # this doesn't particularly put the steps after the Path steps.
+            sequence,
+
+            {
+              "fast_track.pass_fast_option"  => method(:pass_fast_option),
+              "fast_track.fail_fast_option"  => method(:fail_fast_option),
+              "fast_track.fast_track_option" => method(:fast_track_option),
+            },
+            Linear::Insert.method(:Prepend), "path.wirings"
+          )
+        end
+
+        def pass_fast_option((ctx, flow_options), *)
+          ctx = merge_connections_for(ctx, ctx, :pass_fast, :success)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def pass_fast_option_for_pass((ctx, flow_options), *)
+          ctx = merge_connections_for(ctx, ctx, :pass_fast, :failure)
+          ctx = merge_connections_for(ctx, ctx, :pass_fast, :success)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def fail_fast_option((ctx, flow_options), *)
+          ctx = merge_connections_for(ctx, ctx, :fail_fast, :failure)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def fail_fast_option_for_fail((ctx, flow_options), *)
+          ctx = merge_connections_for(ctx, ctx, :fail_fast, :failure)
+          ctx = merge_connections_for(ctx, ctx, :fail_fast, :success)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def fast_track_option((ctx, flow_options), *)
+          return Right, [ctx, flow_options] unless ctx[:fast_track]
+
+          ctx = merge_connections_for(ctx, ctx, :fast_track, :fail_fast, :fail_fast)
+          ctx = merge_connections_for(ctx, ctx, :fast_track, :pass_fast, :pass_fast)
+
+          ctx = merge_outputs_for(ctx,
+            pass_fast: Activity.Output(Activity::FastTrack::PassFast, :pass_fast),
+            fail_fast: Activity.Output(Activity::FastTrack::FailFast, :fail_fast),
+          )
+
+          return Right, [ctx, flow_options]
+        end
+
+        def merge_connections_for(ctx, options, option_name, semantic, magnetic_to=option_name)
+          return ctx unless options[option_name]
+
+          connections  = ctx[:connections].merge(semantic => [Linear::Search.method(:Forward), magnetic_to])
+          ctx          = ctx.merge(connections: connections)
+        end
+
+        def merge_outputs_for(ctx, outputs)
+          ctx = ctx.merge(
+            outputs: outputs.merge(ctx[:outputs])
+          )
+        end
+
+        def initial_sequence(initial_sequence:, fail_fast_end: Activity::End.new(semantic: :fail_fast), pass_fast_end: Activity::End.new(semantic: :pass_fast), **)
+          sequence = initial_sequence
+
+          sequence = Path::DSL.append_end(sequence, task: fail_fast_end, magnetic_to: :fail_fast, id: "End.fail_fast")
+          sequence = Path::DSL.append_end(sequence, task: pass_fast_end, magnetic_to: :pass_fast, id: "End.pass_fast")
+        end
+
+
+
+        # This is slow and should be done only once at compile-time,
+        # DISCUSS: maybe make this a function?
+        # These are the normalizers for an {Activity}, to be injected into a State.
+        Normalizers = Linear::State::Normalizer.new(
+          step: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer ), # here, we extend the generic FastTrack::step_normalizer with the Activity-specific DSL
+          fail: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer_for_fail ),
+          pass: Linear::Normalizer.activity_normalizer( FastTrack::DSL.normalizer_for_pass ),
+        )
+
+        def self.OptionsForState(normalizers: Normalizers, **options)
+          options = Railway::DSL.OptionsForState(options).
+              merge(normalizers: normalizers)
+
+          initial_sequence = FastTrack::DSL.initial_sequence(**options)
+
+          {
+            **options,
+            initial_sequence: initial_sequence,
+          }
+        end
+      end # DSL
+
+      class << self
+        private def fail(*args, &block)
+          recompile_activity_for(:fail, *args, &block) # from Path::Strategy
+        end
+
+        private def pass(*args, &block)
+          recompile_activity_for(:pass, *args, &block) # from Path::Strategy
+        end
+      end
+
+      extend Activity::DSL::Linear::Strategy
+
+      initialize!(Railway::DSL::State.new(DSL.OptionsForState()))
+
+    end # FastTrack
+  end
+end

data/lib/trailblazer/activity/path.rb

@@ -0,0 +1,179 @@
+module Trailblazer
+  class Activity
+    # {Strategy} that helps building simple linear activities.
+    class Path
+      # Functions that help creating a path-specific sequence.
+      module DSL
+        Linear = Activity::DSL::Linear
+
+        module_function
+
+        def normalizer
+          prepend_step_options(
+            initial_sequence(track_name: :success, end_task: Activity::End.new(semantic: :success), end_id: "End.success")
+          )
+        end
+
+        def start_sequence(track_name:)
+          start_default = Activity::Start.new(semantic: :default)
+          start_event   = Linear::Sequence.create_row(task: start_default, id: "Start.default", magnetic_to: nil, wirings: [Linear::Search::Forward(unary_outputs[:success], track_name)])
+          sequence      = Linear::Sequence[start_event]
+        end
+
+        # DISCUSS: still not sure this should sit here.
+        # Pseudo-DSL that prepends {steps} to {sequence}.
+        def prepend_to_path(sequence, steps, insertion_method=Linear::Insert.method(:Prepend), insert_id="End.success")
+          new_rows = steps.collect do |id, task|
+            Linear::Sequence.create_row(
+              task:         task,
+              magnetic_to:  :success,
+              wirings:      [Linear::Search::Forward(unary_outputs[:success], :success)],
+              id:           id,
+            )
+          end
+
+          insertion_method.(sequence, new_rows, insert_id)
+        end
+
+        def unary_outputs
+          {success: Activity::Output(Activity::Right, :success)}
+        end
+
+        def unary_connections(track_name: :success)
+          {success: [Linear::Search.method(:Forward), track_name]}
+        end
+
+        def merge_path_outputs((ctx, flow_options), *)
+          ctx = {outputs: unary_outputs}.merge(ctx)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def merge_path_connections((ctx, flow_options), *)
+          raise unless track_name = ctx[:track_name]# TODO: make track_name required kw.
+          ctx = {connections: unary_connections(track_name: track_name)}.merge(ctx)
+
+          return Right, [ctx, flow_options]
+        end
+
+        # Processes {:before,:after,:replace,:delete} options and
+        # defaults to {before: "End.success"} which, yeah.
+        def normalize_sequence_insert((ctx, flow_options), *)
+          insertion = ctx.keys & sequence_insert_options.keys
+          insertion = insertion[0]   || :before
+          raise if ctx[:end_id].nil? # FIXME
+          target    = ctx[insertion] || ctx[:end_id]
+
+          insertion_method = sequence_insert_options[insertion]
+
+          ctx = ctx.merge(sequence_insert: [Linear::Insert.method(insertion_method), target])
+
+          return Right, [ctx, flow_options]
+        end
+
+        # @private
+        def sequence_insert_options
+          {
+            :before  => :Prepend,
+            :after   => :Append,
+            :replace => :Replace,
+            :delete  => :Delete,
+          }
+        end
+
+        def normalize_magnetic_to((ctx, flow_options), *) # TODO: merge with Railway.merge_magnetic_to
+          raise unless track_name = ctx[:track_name]# TODO: make track_name required kw.
+
+          ctx = {magnetic_to: track_name}.merge(ctx)
+
+          return Right, [ctx, flow_options]
+        end
+
+        # Return {Path::Normalizer} sequence.
+        def prepend_step_options(sequence)
+          prepend_to_path(
+            sequence,
+
+            "path.outputs"          => method(:merge_path_outputs),
+            "path.connections"      => method(:merge_path_connections),
+            "path.sequence_insert"  => method(:normalize_sequence_insert),
+            "path.magnetic_to"      => method(:normalize_magnetic_to),
+            "path.wirings"          => Linear::Normalizer.method(:compile_wirings),
+          )
+        end
+
+        # Returns an initial two-step sequence with {Start.default > End.success}.
+        def initial_sequence(track_name:, end_task:, end_id:)
+          # TODO: this could be an Activity itself but maybe a bit too much for now.
+          sequence = start_sequence(track_name: track_name)
+          sequence = append_end(sequence, task: end_task, magnetic_to: track_name, id: end_id, append_to: "Start.default")
+        end
+
+        def append_end(sequence, **options)
+          sequence = Linear::DSL.insert_task(sequence, **append_end_options(options))
+        end
+
+        def append_end_options(task:, magnetic_to:, id:, append_to: "End.success")
+          end_args = {sequence_insert: [Linear::Insert.method(:Append), append_to], stop_event: true}
+
+          {
+            task:         task,
+            magnetic_to:  magnetic_to,
+            id:           id,
+            wirings:      [
+              Linear::Search::Noop(
+                Activity::Output.new(task, task.to_h[:semantic]), # DISCUSS: do we really want to transport the semantic "in" the object?
+                # magnetic_to
+              )],
+            # outputs:      {magnetic_to => },
+            # connections:  {magnetic_to => [Linear::Search.method(:Noop)]},
+            **end_args
+           }
+        end
+
+        # This is slow and should be done only once at compile-time,
+        # DISCUSS: maybe make this a function?
+        # These are the normalizers for an {Activity}, to be injected into a State.
+        Normalizers = Linear::State::Normalizer.new(
+          step:  Linear::Normalizer.activity_normalizer( Path::DSL.normalizer ), # here, we extend the generic FastTrack::step_normalizer with the Activity-specific DSL
+        )
+
+        def self.OptionsForState(normalizers: Normalizers, track_name: :success, end_task: Activity::End.new(semantic: :success), end_id: "End.success", **options)
+          initial_sequence = Path::DSL.initial_sequence(track_name: track_name, end_task: end_task, end_id: end_id) # DISCUSS: the standard initial_seq could be cached.
+
+          {
+            normalizers:      normalizers,
+            initial_sequence: initial_sequence,
+
+            track_name:             track_name,
+            end_id:                 end_id,
+            step_interface_builder: Activity::TaskBuilder.method(:Binary), # DISCUSS: this is currently the only option we want to pass on in Path() ?
+            adds:                   [],
+            **options
+          }
+        end
+
+        # Implements the actual API ({#step} and friends).
+        # This can be used later to create faster DSLs where the activity is compiled only once, a la
+        #   Path() do  ... end
+        class State < Linear::State
+          def step(*args)
+            seq = Linear::Strategy.task_for!(self, :step, *args) # mutate @state
+          end
+        end
+
+      end # DSL
+
+      extend DSL::Linear::Strategy
+
+      initialize!(Path::DSL::State.new(DSL.OptionsForState()))
+    end # Path
+
+    def self.Path(options)
+      Class.new(Path) do
+        initialize!(Path::DSL::State.new(Path::DSL.OptionsForState(options)))
+      end
+    end
+  end
+end
+

data/lib/trailblazer/activity/railway.rb

@@ -0,0 +1,172 @@
+module Trailblazer
+  # Implementation module that can be passed to `Activity[]`.
+  class Activity
+    class Railway
+      module DSL
+        Linear = Activity::DSL::Linear
+
+        module_function
+
+        def normalizer
+          step_options(Activity::Path::DSL.normalizer)
+        end
+
+        # Change some parts of the "normal" {normalizer} pipeline.
+        # TODO: make this easier, even at this step.
+
+        def normalizer_for_fail
+          sequence = normalizer
+
+          id = "railway.magnetic_to.fail"
+          task = Fail.method(:merge_magnetic_to)
+
+# TODO: use prepend_to_path
+          sequence = Linear::DSL.insert_task(sequence,
+            task: task,
+            magnetic_to: :success, id: id,
+            wirings: [Linear::Search.Forward(Path::DSL.unary_outputs[:success], :success)],
+            sequence_insert: [Linear::Insert.method(:Prepend), "path.wirings"])
+
+          id = "railway.connections.fail.success_to_failure"
+          task = Fail.method(:connect_success_to_failure)
+
+          sequence = Linear::DSL.insert_task(sequence,
+            task: task,
+            magnetic_to: :success, id: id,
+            wirings: [Linear::Search.Forward(Path::DSL.unary_outputs[:success], :success)],
+            sequence_insert: [Linear::Insert.method(:Replace), "path.connections"])
+        end
+
+        def normalizer_for_pass
+          sequence = normalizer
+
+          id = "railway.connections.pass.failure_to_success"
+          task = Pass.method(:connect_failure_to_success)
+
+          sequence = Linear::DSL.insert_task(sequence,
+            task: task,
+            magnetic_to: :success, id: id,
+            wirings: [Linear::Search.Forward(Path::DSL.unary_outputs[:success], :success)],
+            sequence_insert: [Linear::Insert.method(:Append), "path.connections"])
+        end
+
+        module Fail
+          module_function
+
+          def merge_magnetic_to((ctx, flow_options), *)
+            ctx = ctx.merge(magnetic_to: :failure)
+
+            return Right, [ctx, flow_options]
+          end
+
+          def connect_success_to_failure((ctx, flow_options), *)
+            ctx = {connections: {success: [Linear::Search.method(:Forward), :failure]}}.merge(ctx)
+
+            return Right, [ctx, flow_options]
+          end
+        end
+
+        module Pass
+          module_function
+
+          def connect_failure_to_success((ctx, flow_options), *)
+            connections = ctx[:connections].merge({failure: [Linear::Search.method(:Forward), :success]})
+
+            return Right, [ctx.merge(connections: connections), flow_options]
+          end
+        end
+
+        # Add {Railway} steps to normalizer path.
+        def step_options(sequence)
+          Path::DSL.prepend_to_path( # this doesn't particularly put the steps after the Path steps.
+            sequence,
+
+            {
+              "railway.outputs"     => method(:normalize_path_outputs),
+              "railway.connections" => method(:normalize_path_connections),
+            },
+
+            Linear::Insert.method(:Prepend), "path.wirings" # override where it's added.
+          )
+        end
+
+        def normalize_path_outputs((ctx, flow_options), *)
+          outputs = failure_outputs.merge(ctx[:outputs])
+          ctx     = ctx.merge(outputs: outputs)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def normalize_path_connections((ctx, flow_options), *)
+          connections = failure_connections.merge(ctx[:connections])
+          ctx         = ctx.merge(connections: connections)
+
+          return Right, [ctx, flow_options]
+        end
+
+        def failure_outputs
+          {failure: Activity::Output(Activity::Left, :failure)}
+        end
+        def failure_connections
+          {failure: [Linear::Search.method(:Forward), :failure]}
+        end
+
+        def initial_sequence(failure_end:, initial_sequence:, **path_options)
+          # TODO: this could be an Activity itself but maybe a bit too much for now.
+          sequence = Path::DSL.append_end(initial_sequence, task: failure_end, magnetic_to: :failure, id: "End.failure")
+        end
+
+        class State < Path::DSL::State
+          def fail(*args)
+            seq = Linear::Strategy.task_for!(self, :fail, *args) # mutate @state
+          end
+
+          def pass(*args)
+            seq = Linear::Strategy.task_for!(self, :pass, *args) # mutate @state
+          end
+        end # Instance
+
+        Normalizers = Linear::State::Normalizer.new(
+          step:  Linear::Normalizer.activity_normalizer( Railway::DSL.normalizer ), # here, we extend the generic FastTrack::step_normalizer with the Activity-specific DSL
+          fail:  Linear::Normalizer.activity_normalizer( Railway::DSL.normalizer_for_fail ),
+          pass:  Linear::Normalizer.activity_normalizer( Railway::DSL.normalizer_for_pass ),
+        )
+
+
+        def self.OptionsForState(normalizers: Normalizers, failure_end: Activity::End.new(semantic: :failure), **options)
+          options = Path::DSL.OptionsForState(options).
+            merge(normalizers: normalizers, failure_end: failure_end)
+
+          initial_sequence = Railway::DSL.initial_sequence(failure_end: failure_end, **options)
+
+          {
+            **options,
+            initial_sequence: initial_sequence,
+          }
+        end
+
+      end # DSL
+
+      class << self
+        private def fail(*args, &block)
+          recompile_activity_for(:fail, *args, &block)
+        end
+
+        private def pass(*args, &block)
+          recompile_activity_for(:pass, *args, &block)
+        end
+      end
+
+      extend DSL::Linear::Strategy
+
+      initialize!(Railway::DSL::State.new(DSL.OptionsForState()))
+
+    end # Railway
+
+    def self.Railway(options)
+      Class.new(Railway) do
+        initialize!(Railway::DSL::State.new(Railway::DSL.OptionsForState(options)))
+      end
+    end
+  end
+end