trailblazer-activity-dsl-linear 0.5.0 → 1.0.0.beta1

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

@@ -0,0 +1,298 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        # Normalizer-steps to implement {:input} and {:output}
+        # Returns an Extension instance to be thrown into the `step` DSL arguments.
+        def self.VariableMapping(input_id: "task_wrap.input", output_id: "task_wrap.output", **options)
+          input, output, normalizer_options, non_symbol_options = VariableMapping.merge_instructions_from_dsl(**options)
+
+          extension = VariableMapping.Extension(input, output)
+
+          return TaskWrap::Extension::WrapStatic.new(extension: extension), normalizer_options, non_symbol_options
+        end
+
+        module VariableMapping
+          # Add our normalizer steps to the strategy's normalizer.
+          def self.extend!(strategy, *step_methods) # DISCUSS: should this be implemented in Linear?
+            Linear::Normalizer.extend!(strategy, *step_methods) do |normalizer|
+              Linear::Normalizer.prepend_to(
+                normalizer,
+                "activity.wirings",
+                {
+                   # In(), Out(), {:input}, Inject() feature
+                  "activity.normalize_input_output_filters" => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:normalize_input_output_filters)),
+                  "activity.input_output_dsl"               => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:input_output_dsl)),
+                }
+              )
+            end
+          end
+
+          def self.Extension(input, output, input_id: "task_wrap.input", output_id: "task_wrap.output")
+            TaskWrap.Extension(
+              [input,  id: input_id,  prepend: "task_wrap.call_task"],
+              [output, id: output_id, append: "task_wrap.call_task"]
+            )
+          end
+
+          # Steps that are added to the DSL normalizer.
+          module Normalizer
+            # Process {In() => [:model], Inject() => [:current_user], Out() => [:model]}
+            def self.normalize_input_output_filters(ctx, non_symbol_options:, **)
+              input_exts  = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::In) }
+              output_exts = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::Out) }
+              inject_exts = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::Inject) }
+
+              return unless input_exts.any? || output_exts.any? || inject_exts.any?
+
+              ctx[:inject_filters] = inject_exts
+              ctx[:in_filters]     = input_exts
+              ctx[:out_filters]    = output_exts
+            end
+
+            def self.input_output_dsl(ctx, extensions: [], **options)
+              # no :input/:output/:inject/Input()/Output() passed.
+              return if (options.keys & [:input, :output, :inject, :inject_filters, :in_filters, :output_filters]).empty?
+
+              extension, normalizer_options, non_symbol_options = Linear.VariableMapping(**options)
+
+              ctx[:extensions] = extensions + [extension] # FIXME: allow {Extension() => extension}
+              ctx.merge!(**normalizer_options) # DISCUSS: is there another way of merging variables into ctx?
+              ctx[:non_symbol_options].merge!(non_symbol_options)
+            end
+          end
+
+          module_function
+
+          # For the input filter we
+          #   1. create a separate {Pipeline} instance {pipe}. Depending on the user's options, this might have up to four steps.
+          #   2. The {pipe} is run in a lamdba {input}, the lambda returns the pipe's ctx[:input_ctx].
+          #   3. The {input} filter in turn is wrapped into an {Activity::TaskWrap::Input} object via {#merge_instructions_for}.
+          #   4. The {TaskWrap::Input} instance is then finally placed into the taskWrap as {"task_wrap.input"}.
+          #
+          # @private
+          #
+
+            # default_input
+          #  <or>
+            # oldway
+            #   :input
+            #   :inject
+            # newway(initial_input_pipeline)
+            #   In,Inject
+          # => input_pipe
+          def merge_instructions_from_dsl(**options)
+            # The overriding {:input} option is set.
+            pipeline, has_mono_options, _ = DSL.pipe_for_mono_input(**options)
+
+            if ! has_mono_options
+              pipeline = DSL.pipe_for_composable_input(**options)  # FIXME: rename filters consistently
+            end
+
+            # gets wrapped by {VariableMapping::Input} and called there.
+            # API: @filter.([ctx, original_flow_options], **original_circuit_options)
+            # input = Trailblazer::Option(->(original_ctx, **) {  })
+            input  = Pipe::Input.new(pipeline)
+
+
+            output_pipeline, has_mono_options, _ = DSL.pipe_for_mono_output(**options)
+
+            if ! has_mono_options
+              output_pipeline = DSL.pipe_for_composable_output(**options)
+            end
+
+            output = Pipe::Output.new(output_pipeline)
+
+            return input, output,
+              # normalizer_options:
+              {
+                variable_mapping_pipelines: [pipeline, output_pipeline],
+              },
+              # non_symbol_options:
+              {
+                Linear::Strategy.DataVariable() => :variable_mapping_pipelines # we want to store {:variable_mapping_pipelines} in {Row.data} for later reference.
+              }
+              # DISCUSS: should we remember the pure pipelines or get it from the compiled extension?
+              # store pipe in the extension (via TW::Extension.data)?
+          end
+
+# < AddVariables
+#   Option
+#     filter
+#   merge_variables
+
+          # Runtime classes
+          Filter = Struct.new(:aggregate_step, :filter, :name, :add_variables_class)
+
+          # These objects are created via the DSL, keep all i/o steps in a Pipeline
+          # and run the latter when being `call`ed.
+          module Pipe
+            class Input
+              def initialize(pipe, id: :vm_original_ctx)
+                @pipe = pipe
+                @id   = id # DISCUSS: untested.
+              end
+
+              def call(wrap_ctx, original_args)
+                (original_ctx, original_flow_options), original_circuit_options = original_args
+
+                # let user compute new ctx for the wrapped task.
+                pipe_ctx, _ = @pipe.({original_ctx: original_ctx}, [[original_ctx, original_flow_options], original_circuit_options])
+                input_ctx   = pipe_ctx[:input_ctx]
+
+                wrap_ctx = wrap_ctx.merge(@id => original_ctx) # remember the original ctx under the key {:vm_original_ctx}.
+
+                # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
+                return wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options]
+              end
+            end
+
+            # API in VariableMapping::Output:
+            #   output_ctx = @filter.(returned_ctx, [original_ctx, returned_flow_options], **original_circuit_options)
+            # Returns {output_ctx} that is used after taskWrap finished.
+            class Output < Input
+              # def call(returned_ctx, (original_ctx, returned_flow_options), **original_circuit_options)
+                def call(wrap_ctx, original_args)
+                  returned_ctx, returned_flow_options = wrap_ctx[:return_args]  # this is the Context returned from {call}ing the wrapped user task.
+                  original_ctx                        = wrap_ctx[@id]           # grab the original ctx from before which was set in the {:input} filter.
+                  _, original_circuit_options         = original_args
+
+                # let user compute the output.
+                pipe_ctx, _ = @pipe.({original_ctx: original_ctx, returned_ctx: returned_ctx}, [[original_ctx, returned_flow_options], original_circuit_options])
+
+                output_ctx  = pipe_ctx[:aggregate]
+
+                wrap_ctx = wrap_ctx.merge(return_args: [output_ctx, returned_flow_options]) # DISCUSS: this won't allow tracing in the taskWrap as we're returning {returned_flow_options} from above.
+
+                return wrap_ctx, original_args
+              end
+            end
+          end
+
+# DISCUSS: improvable sections such as merge vs hash[]=
+          def initial_aggregate(wrap_ctx, original_args)
+            wrap_ctx = wrap_ctx.merge(aggregate: {})
+
+            return wrap_ctx, original_args
+          end
+
+          # Merge all original ctx variables into the new input_ctx.
+          # This happens when no {:input} is provided.
+          def default_input_ctx(wrap_ctx, original_args)
+            default_ctx = wrap_ctx[:original_ctx]
+
+            merge_variables(default_ctx, wrap_ctx, original_args)
+          end
+
+          # Input/output Pipeline step that runs the user's {filter} and adds
+          # variables to the computed ctx.
+          #
+          # Basically implements {:input}.
+          #
+# AddVariables: I call something with an Option-interface and run the return value through merge_variables().
+          # works on {:aggregate} by (usually) producing a hash fragment that is merged with the existing {:aggregate}
+          class AddVariables
+            def initialize(filter, user_filter)
+              @filter      = filter # The users input/output filter.
+              @user_filter = user_filter # this is for introspection.
+            end
+
+            def call(wrap_ctx, original_args)
+              ((original_ctx, _), circuit_options) = original_args
+              # puts "@@@@@ #{wrap_ctx[:returned_ctx].inspect}"
+
+              # this is the actual logic.
+              variables = call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+
+              VariableMapping.merge_variables(variables, wrap_ctx, original_args)
+            end
+
+            def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+              _variables = @filter.(original_ctx, keyword_arguments: original_ctx.to_hash, **circuit_options)
+            end
+
+            class ReadFromAggregate < AddVariables # FIXME: REFACTOR
+              def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+                new_ctx = wrap_ctx[:aggregate]
+
+                _variables = @filter.(new_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
+              end
+            end
+
+            class Output < AddVariables
+              def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+                new_ctx = wrap_ctx[:returned_ctx]
+
+                @filter.(new_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
+              end
+
+              # Pass {inner_ctx, outer_ctx, **inner_ctx}
+              class WithOuterContext < Output
+                def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+                  new_ctx = wrap_ctx[:returned_ctx]
+
+                  @filter.(new_ctx, original_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
+                end
+              end
+
+              # Always deletes from {:aggregate}.
+              class Delete < AddVariables
+                def call(wrap_ctx, original_args)
+                  @filter.collect do |name|
+                    wrap_ctx[:aggregate].delete(name) # FIXME: we're mutating a hash here!
+                  end
+
+                  return wrap_ctx, original_args
+                end
+              end
+            end
+          end
+
+          # Finally, create a new input ctx from all the
+          # collected input variables.
+          # This goes into the step/nested OP.
+          def scope(wrap_ctx, original_args)
+            ((_, flow_options), _) = original_args
+
+            # this is the actual context passed into the step.
+            wrap_ctx[:input_ctx] = Trailblazer::Context(
+              wrap_ctx[:aggregate],
+              {}, # mutable variables
+              flow_options[:context_options]
+            )
+
+            return wrap_ctx, original_args
+          end
+
+          # Last call in every step. Currently replaces {:input_ctx} by adding variables using {#merge}.
+          # DISCUSS: improve here?
+          def merge_variables(variables, wrap_ctx, original_args)
+            wrap_ctx[:aggregate] = wrap_ctx[:aggregate].merge(variables)
+
+            return wrap_ctx, original_args
+          end
+
+          # @private
+          # The default {:output} filter only returns the "mutable" part of the inner ctx.
+          # This means only variables added using {inner_ctx[..]=} are merged on the outside.
+          def default_output_ctx(wrap_ctx, original_args)
+            new_ctx = wrap_ctx[:returned_ctx]
+
+            _wrapped, mutable = new_ctx.decompose # `_wrapped` is what the `:input` filter returned, `mutable` is what the task wrote to `scoped`.
+
+            merge_variables(mutable, wrap_ctx, original_args)
+          end
+
+          def merge_with_original(wrap_ctx, original_args)
+            original_ctx     = wrap_ctx[:original_ctx]  # outer ctx
+            output_variables = wrap_ctx[:aggregate]
+
+            wrap_ctx[:aggregate] = original_ctx.merge(output_variables) # FIXME: use merge_variables()
+            # pp wrap_ctx
+            return wrap_ctx, original_args
+          end
+        end # VariableMapping
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        module Helper
+          # Normalizer logic for {Path() do end}.
+          #
+          # TODO: it would be cool to be able to connect an (empty) path to specific termini,
+          #       this would work if we could add multiple magnetic_to.
+          module Path
+            # Normalizer steps to handle Path() macro.
+            module Normalizer
+              module_function
+              # Replace a block-expecting {PathBranch} instance with another one that's holding
+              # the global {:block} from {#step ... do end}.
+              def forward_block_for_path_branch(ctx, options:, normalizer_options:, library_options:, **)
+                block              = options[:block]
+                non_symbol_options = options[:non_symbol_options]
+
+                return unless block
+
+                output, path_branch =
+                  non_symbol_options.find { |output, cfg| cfg.kind_of?(Linear::PathBranch) }
+
+                path_branch_with_block = Linear::PathBranch.new(
+                  normalizer_options.
+                    merge(path_branch.options).
+                    merge(block: block)
+                )
+
+                ctx[:options] = ctx[:options].merge(non_symbol_options: non_symbol_options.merge(output => path_branch_with_block))
+              end
+
+              # Convert all occurrences of Path() to a corresponding {Track}.
+              # The {Track} instance contains all additional {adds} steps and
+              # is picked up in {Normalizer.normalize_connections_from_dsl}.
+              def convert_paths_to_tracks(ctx, non_symbol_options:, block: false, **)
+                new_tracks = non_symbol_options.
+                  find_all { |output, cfg| cfg.kind_of?(Linear::PathBranch) }.
+                  collect {  |output, cfg| [output, Path.convert_path_to_track(block: ctx[:block], **cfg.options)]  }.
+                  to_h
+
+                ctx[:non_symbol_options] = non_symbol_options.merge(new_tracks)
+              end
+            end # Normalizer
+
+            module_function
+
+            def convert_path_to_track(track_color: "track_#{rand}", connect_to: nil, before: false, block: nil, **options)
+              # DISCUSS:  if anyone overrides `#step` in the "outer" activity, this won't be applied inside the branch.
+
+              # DISCUSS: use Path::Sequencer::Builder here instead?
+              path = Activity::Path(**options, track_name: track_color, &block)
+
+              seq = path.to_h[:sequence]
+              # Strip default ends `Start.default` and `End.success` (if present).
+              seq = seq[1..-1].reject{ |row| row[3][:stop_event] && row.id == 'End.success' }
+
+              if connect_to
+                seq = connect_for_sequence(seq, connect_to: connect_to)
+              end
+
+              # Add the path elements before {End.success}.
+              # Termini (or :stop_event) are to be placed after {End.success}.
+              adds = seq.collect do |row|
+                options = row[3]
+
+                # the terminus of the path goes _after_ {End.success} into the "end group".
+                insert_method = options[:stop_event] ? Activity::Adds::Insert.method(:Append) : Activity::Adds::Insert.method(:Prepend)
+
+                insert_target = "End.success" # insert before/after
+                insert_target = before if before && connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Track) # FIXME: this is a bit hacky, of course!
+
+                {
+                  row:    row,
+                  insert: [insert_method, insert_target]
+                }
+              end
+
+              # Connect the Output() => Track(path_track)
+              return Linear::Track.new(track_color, adds, {})
+            end
+
+            # Connect last row of the {sequence} to the given step via its {Id}
+            # Useful when steps needs to be inserted in between {Start} and {connect Id()}.
+            private def connect_for_sequence(sequence, connect_to:)
+              output, _ = sequence[-1][2][0].(sequence, sequence[-1]) # FIXME: the Forward() proc contains the row's Output, and the only current way to retrieve it is calling the search strategy. It should be Forward#to_h
+
+              # searches = [Search.ById(output, connect_to.value)]
+              searches = [Sequence::Search.ById(output, connect_to.value)] if connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Id)
+              searches = [Sequence::Search.Forward(output, connect_to.color)] if connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Track) # FIXME: use existing mapping logic!
+
+              row = sequence[-1]
+              row = row[0..1] + [searches] + [row[3]] # FIXME: not mutating an array is so hard: we only want to replace the "searches" element, index 2
+              row = Sequence::Row[*row]
+
+              sequence = sequence[0..-2] + [row]
+
+              sequence
+            end
+          end # Path
+        end
+      end
+    end
+  end
+end

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

@@ -2,151 +2,77 @@ module Trailblazer
   class Activity
     module DSL
       module Linear
-        module Helper
-          # @api private
-          OutputSemantic = Struct.new(:value)
-          Id             = Struct.new(:value)
-          Track          = Struct.new(:color, :adds, :options)
-          Extension      = Struct.new(:callable) do
-            def call(*args, &block)
-              callable.(*args, &block)
-            end
+        # Data Structures used in the DSL. They're mostly created from helpers
+        # and then get processed in the normalizer.
+        #
+        # @private
+        OutputSemantic = Struct.new(:value)
+        Id             = Struct.new(:value)
+        Track          = Struct.new(:color, :adds, :options)
+        Extension      = Struct.new(:callable) do
+          def call(*args, &block)
+            callable.(*args, &block)
           end
+        end
+        PathBranch       = Struct.new(:options)
+        DataVariableName = Class.new
 
-          def self.included(base)
-            base.extend ClassMethods
+        # Shortcut functions for the DSL.
+        # Those are included in {Strategy} so they're available to all Strategy users such
+        # as {Railway} or {Operation}.
+        module Helper
+          # This is the namespace container for {Contract::}, {Policy::} and friends.
+          module Constants
           end
 
-          # Shortcut functions for the DSL.
-          module ClassMethods
-            #   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, wrap_around: false)
-              Track.new(color, [], wrap_around: wrap_around).freeze
-            end
-
-            def Id(id)
-              Id.new(id).freeze
-            end
-
-            def Path(track_color: "track_#{rand}", connect_to: nil, before: false, **options, &block)
-              path      = Activity::Path(track_name: track_color, **options)
-              activity  = Class.new(path) { self.instance_exec(&block) }
-
-              seq = activity.instance_variable_get(:@state).to_h[:sequence] # TODO: fix @state interface
-              # Strip default ends `Start.default` and `End.success` (if present).
-              seq = seq[1..-1].reject{ |row| row[3][:stop_event] && row[3][:id] == 'End.success' }
-
-              if connect_to
-                seq = connect_for_sequence(seq, connect_to: connect_to)
-              end
-
-              # Add the path elements before {End.success}.
-              # Termini (or :stop_event) are to be placed after {End.success}.
-              adds = seq.collect do |row|
-                options = row[3]
-
-                # the terminus of the path goes _after_ {End.success} into the "end group".
-                insert_method = options[:stop_event] ? Insert.method(:Append) : Insert.method(:Prepend)
-
-                insert_target = "End.success" # insert before/after
-                insert_target = before if before && connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Helper::Track) # FIXME: this is a bit hacky, of course!
-
-                {
-                  row:    row,
-                  insert: [insert_method, insert_target]
-                }
-              end
+          #   Output( Left, :failure )
+          #   Output( :failure ) #=> Output::Semantic
+          def Output(signal, semantic=nil)
+            return OutputSemantic.new(signal) if semantic.nil?
 
-              # Connect the Output() => Track(path_track)
-              return Track.new(track_color, adds, {})
-            end
-
-            # Connect last row of the {sequence} to the given step via its {Id}
-            # Useful when steps needs to be inserted in between {Start} and {connect Id()}.
-            private def connect_for_sequence(sequence, connect_to:)
-              output, _ = sequence[-1][2][0].(sequence, sequence[-1]) # FIXME: the Forward() proc contains the row's Output, and the only current way to retrieve it is calling the search strategy. It should be Forward#to_h
-
-              # searches = [Search.ById(output, connect_to.value)]
-              searches = [Search.ById(output, connect_to.value)] if connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Helper::Id)
-              searches = [Search.Forward(output, connect_to.color)] if connect_to.instance_of?(Trailblazer::Activity::DSL::Linear::Helper::Track) # FIXME: use existing mapping logic!
-
-              row = sequence[-1]
-              row = row[0..1] + [searches] + [row[3]] # FIXME: not mutating an array is so hard: we only want to replace the "searches" element, index 2
-
-              sequence = sequence[0..-2] + [row]
-
-              sequence
-            end
-
-            # Computes the {:outputs} options for {activity}.
-            def Subprocess(activity, patch: {})
-              activity = Patch.customize(activity, options: patch)
+            Activity.Output(signal, semantic)
+          end
 
-              {
-                task:    activity,
-                outputs: Hash[activity.to_h[:outputs].collect { |output| [output.semantic, output] }]
-              }
-            end
+          def End(semantic)
+            Activity.End(semantic)
+          end
 
-            module Patch
-              module_function
+          def end_id(semantic:, **)
+            "End.#{semantic}" # TODO: use everywhere
+          end
 
-              def customize(activity, options:)
-                options = options.is_a?(Proc) ?
-                  { [] => options } : # hash-wrapping with empty path, for patching given activity itself
-                  options
+          def Track(color, wrap_around: false)
+            Track.new(color, [], wrap_around: wrap_around).freeze
+          end
 
-                options.each do |path, patch|
-                  activity = call(activity, path, patch) # TODO: test if multiple patches works!
-                end
+          def Id(id)
+            Id.new(id).freeze
+          end
 
-                activity
-              end
+          def Path(**options, &block)
+            options = options.merge(block: block) if block_given?
 
-              def call(activity, path, customization)
-                task_id, *path = path
+            Linear::PathBranch.new(options) # picked up by normalizer.
+          end
 
-                patch =
-                  if task_id
-                    segment_activity = Introspect::Graph(activity).find(task_id).task
-                    patched_segment_activity = call(segment_activity, path, customization)
+          # Computes the {:outputs} options for {activity}.
+          def Subprocess(activity, patch: {})
+            activity = Patch.customize(activity, options: patch)
 
-                    # Replace the patched subprocess.
-                    -> { step Subprocess(patched_segment_activity), inherit: true, replace: task_id, id: task_id }
-                  else
-                    customization # apply the *actual* patch from the Subprocess() call.
-                  end
+            {
+              task:    activity,
+              outputs: Hash[activity.to_h[:outputs].collect { |output| [output.semantic, output] }]
+            }
+          end
 
-                patched_activity = Class.new(activity)
-                patched_activity.class_exec(&patch)
-                patched_activity
-              end
-            end
+          def In(**kws);     VariableMapping::DSL::In(**kws); end
+          def Out(**kws);    VariableMapping::DSL::Out(**kws); end
+          def Inject(**kws); VariableMapping::DSL::Inject(**kws); 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
+          def DataVariable
+            DataVariableName.new
           end
         end # Helper
-
-        include Helper # Introduce Helper constants in DSL::Linear scope
       end # Linear
     end # DSL
   end # Activity