trailblazer-future 2.1.0.rc1

data/lib/trailblazer/v2_1/activity/testing.rb

@@ -0,0 +1,32 @@
+# DISCUSS: move to trailblazer-activity-test ?
+
+# Helpers to quickly create steps and tasks.
+module Trailblazer::V2_1::Activity::Testing
+  # Creates a module with one step method for each name.
+  #
+  # @example
+  #   extend T.def_steps(:create, :save)
+  def self.def_steps(*names)
+    Module.new do
+      names.each do |name|
+        define_method(name) do | ctx, ** |
+          ctx[:seq] << name
+          ctx.key?(name) ? ctx[name] : true
+        end
+      end
+    end
+  end
+
+  # Creates a method instance with a task interface.
+  #
+  # @example
+  #   task task: T.def_task(:create)
+  def self.def_task(name)
+    Module.new do
+      define_singleton_method(name) do | (ctx, flow_options), ** |
+        ctx[:seq] << name
+        return Trailblazer::V2_1::Activity::Right, [ctx, flow_options]
+      end
+    end.method(name)
+  end
+end

data/lib/trailblazer/v2_1/activity/trace.rb

@@ -0,0 +1,97 @@
+module Trailblazer::V2_1
+  class Activity < Module   # Trace#call will call the activities and trace what steps are called, options passed,
+    # and the order and nesting.
+    #
+    #   stack, _ = Trailblazer::V2_1::Activity::Trace.(activity, activity[:Start], { id: 1 })
+    #   puts Trailblazer::V2_1::Activity::Present.tree(stack) # renders the trail.
+    #
+    # Hooks into the taskWrap.
+    module Trace
+      class << self
+        # {:argumenter} API
+        # FIXME: needs Introspect.arguments_for_call
+        # FIXME: needs TaskWrap.arguments_for_call
+        def arguments_for_call(activity, (options, flow_options), **circuit_options)
+          tracing_flow_options = {
+            stack:         Trace::Stack.new,
+          }
+
+          tracing_circuit_options = {
+            wrap_runtime:  ::Hash.new(Trace.wirings), # FIXME: this still overrides existing :wrap_runtime.
+          }
+
+          return activity, [ options, tracing_flow_options.merge(flow_options) ], circuit_options.merge(tracing_circuit_options)
+        end
+
+        def call(activity, (options, flow_options), circuit_options={})
+          activity, (options, flow_options), circuit_options = Trace.arguments_for_call( activity, [options, flow_options], circuit_options ) # only run once for the entire circuit!
+
+          last_signal, (options, flow_options) =
+            Activity::TaskWrap.invoke(activity, [options, flow_options], circuit_options)
+
+          return flow_options[:stack], last_signal, [options, flow_options]
+        end
+
+        alias_method :invoke, :call
+
+        # Insertions for the trace tasks that capture the arguments just before calling the task,
+        # and before the TaskWrap is finished.
+        #
+        # Note that the TaskWrap steps are implemented in Activity::TaskWrap::Trace.
+        #
+        # @private
+        def wirings
+          Module.new do
+            extend Activity::Path::Plan()
+
+            task TaskWrap::Trace.method(:capture_args),   id: "task_wrap.capture_args",   before: "task_wrap.call_task"
+            task TaskWrap::Trace.method(:capture_return), id: "task_wrap.capture_return", before: "End.success", group: :end
+          end
+        end
+      end
+
+      Entity = Struct.new(:task, :activity, :data)
+      class Entity::Input < Entity
+      end
+
+      class Entity::Output < Entity
+      end
+
+      class Task < Array
+        def inspect
+          %{<Task>#{super}}
+        end
+      end
+
+      # Mutable/stateful per design. We want a (global) stack!
+      class Stack
+        def initialize
+          @nested  = []
+          @stack   = [ @nested ]
+        end
+
+        def indent!
+          current << indented = Task.new
+          @stack << indented
+        end
+
+        def unindent!
+          @stack.pop
+        end
+
+        def <<(args)
+          current << args
+        end
+
+        def to_a
+          @nested
+        end
+
+        private
+        def current
+          @stack.last
+        end
+      end # Stack
+    end
+  end
+end

data/lib/trailblazer/v2_1/circuit.rb

@@ -0,0 +1,71 @@
+module Trailblazer::V2_1
+  # Running a Circuit instance will run all tasks sequentially depending on the former's result.
+  # Each task is called and retrieves the former task's return values.
+  #
+  # Note: Please use #Activity as a public circuit builder.
+  #
+  # @param map         [Hash] Defines the wiring.
+  # @param stop_events [Array] Tasks that stop execution of the circuit.
+  #
+  #   result = circuit.(start_at, *args)
+  #
+  # @see Activity
+  # @api semi-private
+  #
+  # This is the "pipeline operator"'s implementation.
+  class Circuit
+    def initialize(map, stop_events, start_task:, name: nil)
+      @map         = map
+      @stop_events = stop_events
+      @name        = name
+      @start_task  = start_task
+    end
+
+    # @param args [Array] all arguments to be passed to the task's `call`
+    # @param task [callable] task to call
+    Run = ->(task, args, **circuit_options) { task.(args, **circuit_options) }
+
+    # Runs the circuit until we hit a stop event.
+    #
+    # This method throws exceptions when the returned value of a task doesn't match
+    # any wiring.
+    #
+    # @param task An event or task of this circuit from where to start
+    # @param options anything you want to pass to the first task
+    # @param flow_options Library-specific flow control data
+    # @return [last_signal, options, flow_options, *args]
+    #
+    # NOTE: returned circuit_options are discarded when calling the runner.
+    def call(args, start_task: @start_task, runner: Run, **circuit_options)
+      circuit_options = circuit_options.merge( runner: runner ).freeze # TODO: set the :runner option via arguments_for_call to save the merge?
+      task            = start_task
+
+      loop do
+        last_signal, args, _discarded_circuit_options = runner.(
+          task,
+          args,
+          circuit_options
+        )
+
+        # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
+        return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
+
+        task = next_for(task, last_signal) or raise IllegalSignalError.new("<#{@name}>[#{task}][ #{last_signal.inspect} ]")
+      end
+    end
+
+    # Returns the circuit's components.
+    def to_h
+      { map: @map, end_events: @stop_events, start_task: @start_task }
+    end
+
+  private
+    def next_for(last_task, signal)
+      outputs = @map[last_task]
+      outputs[signal]
+    end
+
+    class IllegalSignalError < RuntimeError
+    end
+  end
+end

data/lib/trailblazer/v2_1/container_chain.rb

@@ -0,0 +1,45 @@
+# @private
+class Trailblazer::V2_1::Context::ContainerChain # used to be called Resolver.
+  # Keeps a list of containers. When looking up a key/value, containers are traversed in
+  # the order they were added until key is found.
+  #
+  # Required Container interface: `#key?`, `#[]`.
+  #
+  # @note ContainerChain is an immutable data structure, it does not support writing.
+  # @param containers Array of <Container> objects (splatted)
+  def initialize(containers, to_hash: nil)
+    @containers = containers
+    @to_hash    = to_hash
+  end
+
+  # @param name Symbol or String to lookup a value stored in one of the containers.
+  def [](name)
+    self.class.find(@containers, name)
+  end
+
+  # @private
+  def key?(name)
+    @containers.find { |container| container.key?(name) }
+  end
+
+  def self.find(containers, name)
+    containers.find { |container| container.key?(name) && (return container[name]) }
+  end
+
+  def keys
+    @containers.collect(&:keys).flatten
+end
+
+  # @private
+  def to_hash
+    return @to_hash.(@containers) if @to_hash # FIXME: introduce pattern matching so we can have different "transformers" for each container type.
+    @containers.each_with_object({}) { |container, hash| hash.merge!(container.to_hash) }
+  end
+end
+
+# alternative implementation:
+# containers.reverse.each do |container| @mutable_options.merge!(container) end
+#
+# benchmark, merging in #initialize vs. this resolver.
+#                merge     39.678k (± 9.1%) i/s -    198.700k in   5.056653s
+#             resolver     68.928k (± 6.4%) i/s -    342.836k in   5.001610s

data/lib/trailblazer/v2_1/context.rb

@@ -0,0 +1,79 @@
+# TODO: mark/make all but mutable_options as frozen.
+# The idea of Skill is to have a generic, ordered read/write interface that
+# collects mutable runtime-computed data while providing access to compile-time
+# information.
+# The runtime-data takes precedence over the class data.
+#
+# notes
+# a context is a ContainerChain with two elements (when reading)
+module Trailblazer::V2_1
+  # Holds local options (aka `mutable_options`) and "original" options from the "outer"
+  # activity (aka wrapped_options).
+
+  # only public creator: Build
+  class Context # :data object:
+    def initialize(wrapped_options, mutable_options)
+      @wrapped_options, @mutable_options = wrapped_options, mutable_options
+      # TODO: wrapped_options should be optimized for lookups here since it could also be a Context instance, but should be a ContainerChain.
+    end
+
+    def [](name)
+      # ContainerChain.find( [@mutable_options, @wrapped_options], name )
+
+      # in 99.9% or cases @mutable_options will be a Hash, and these are already optimized for lookups.
+      # it's up to the ContainerChain to optimize itself.
+      return @mutable_options[name] if @mutable_options.key?(name)
+      @wrapped_options[name]
+    end
+
+    # TODO: use ContainerChain.find here for a generic optimization
+    #
+    # the version here is about 4x faster for now.
+    def key?(name)
+      # ContainerChain.find( [@mutable_options, @wrapped_options], name )
+      @mutable_options.key?(name) || @wrapped_options.key?(name)
+    end
+
+    def []=(name, value)
+      @mutable_options[name] = value
+    end
+
+    # @private
+    #
+    # This method might be removed.
+    def merge(hash)
+      original, mutable_options = decompose
+
+      ctx = Trailblazer::V2_1::Context( original, mutable_options.merge(hash) )
+    end
+
+    # Return the Context's two components. Used when computing the new output for
+    # the next activity.
+    def decompose
+      [ @wrapped_options, @mutable_options ]
+    end
+
+    def keys
+      @mutable_options.keys + @wrapped_options.keys # FIXME.
+    end
+
+
+
+    # TODO: maybe we shouldn't allow to_hash from context?
+    # TODO: massive performance bottleneck. also, we could already "know" here what keys the
+    # transformation wants.
+    # FIXME: ToKeywordArguments()
+    def to_hash
+      {}.tap do |hash|
+        # the "key" here is to call to_hash on all containers.
+        [ @wrapped_options.to_hash, @mutable_options.to_hash ].each do |options|
+          options.each { |k, v| hash[k.to_sym] = v }
+        end
+      end
+    end
+  end
+
+  def self.Context(wrapped_options, mutable_options={})
+    Context.new(wrapped_options, mutable_options)
+  end
+end # Trailblazer::V2_1

data/lib/trailblazer/v2_1/deprecation/call.rb

@@ -0,0 +1,46 @@
+module Trailblazer::V2_1
+  module Deprecation
+    module Operation
+      # This is super hacky. Fix you call calls everywhere (shouldn't take too long) and never load this file, again.
+      module Call
+        def self.options_for_call(params, *containers)
+          if containers == []
+            if params.is_a?(Hash) # this means we assume everything is cool. Create.( {...} )
+
+            else # this means someone did Create.( #<WeirdParamsObject> )
+              deprecate_positional_params(params, *containers)
+              return { params: params }, *containers
+            end
+          else # Create.( params, "current_user" => ... )
+            options, containers = containers[0], (containers[1..-1] || [])
+            if options.is_a?(Hash) # old API
+              warn "[Trailblazer::V2_1] Please don't pass the `params` object as a positional argument into `Operation.()`, use the `:params` key and one hash for all: `Operation.( params: my_params, current_user: ... )` ."
+              return options.merge( params: params ), *containers
+            end
+          end
+
+          return params, *containers
+        end
+
+        def self.deprecate_positional_params(params, *containers)
+          warn "[Trailblazer::V2_1] Please don't pass the `params` object as a positional argument into `Operation.()`, use the `:params` key: `Operation.( params: my_params )` ."
+        end
+      end
+    end
+  end
+end
+
+Trailblazer::V2_1::Operation.module_eval do
+  # this sucks:
+  def self.call(options={}, *containers)
+    options, *containers = Trailblazer::V2_1::Deprecation::Operation::Call.options_for_call(options, *containers)
+
+    ctx = Trailblazer::V2_1::Operation::PublicCall.options_for_public_call(options, *containers)
+
+    # call the activity.
+    last_signal, (options, flow_options) = __call__( [ctx, {}] ) # Railway::call # DISCUSS: this could be ::call_with_context.
+
+    # Result is successful if the activity ended with an End event derived from Railway::End::Success.
+    Trailblazer::V2_1::Operation::Railway::Result(last_signal, options, flow_options)
+  end
+end

data/lib/trailblazer/v2_1/deprecation/context.rb

@@ -0,0 +1,43 @@
+module Trailblazer::V2_1
+  module Deprecation
+    class ContextWithIndifferentAccess < Trailblazer::V2_1::Context
+      def [](key)
+        return super unless Trailblazer::V2_1::Operation::PublicCall.deprecatable?(key)
+        key, _ = Trailblazer::V2_1::Operation::PublicCall.deprecate_string(key, nil)
+        super(key)
+      end
+
+      def []=(key, value)
+        return super unless Trailblazer::V2_1::Operation::PublicCall.deprecatable?(key)
+        key, _ = Trailblazer::V2_1::Operation::PublicCall.deprecate_string(key, nil)
+        super(key, value)
+      end
+    end
+  end
+end
+
+Trailblazer::V2_1::Operation::PublicCall.module_eval do
+  def self.options_for_public_call(options={}, *containers)
+    hash_transformer = ->(containers) { containers[0].to_hash } # FIXME: don't transform any containers into kw args.
+
+    options = deprecate_strings(options)
+
+    immutable_options = Trailblazer::V2_1::Context::ContainerChain.new( [options, *containers], to_hash: hash_transformer ) # Runtime options, immutable.
+
+    Trailblazer::V2_1::Deprecation::ContextWithIndifferentAccess.new(immutable_options, {})
+  end
+
+  def self.deprecatable?(key)
+    key.is_a?(String) && key.split(".").size == 1
+  end
+
+  def self.deprecate_strings(options)
+    ary = options.collect { |k,v| deprecatable?(k) ? deprecate_string(k, v) : [k,v]  }
+    Hash[ary]
+  end
+
+  def self.deprecate_string(key, value)
+    warn "[Trailblazer::V2_1] Using a string key for non-namespaced keys is deprecated. Please use `:#{key}` instead of `#{key.inspect}`."
+    [ key.to_sym, value ]
+  end
+end

data/lib/trailblazer/v2_1/dsl.rb

@@ -0,0 +1,47 @@
+module Trailblazer::V2_1
+  module DSL
+    # Boring DSL code that allows to set a skill class, or define it ad-hoc using a block.
+    # passing a constant always wipes out the existing class.
+    #
+    # Used in Contract, Representer, Callback, ..
+    class Build
+      # options[:prefix]
+      # options[:class]
+      # options[:container]
+
+      # Currently, adds .class only to classes. this could break builder instances?
+
+      def call(options, name=nil, constant=nil, dsl_block, &block)
+        # contract MyForm
+        if name.is_a?(Class)
+          constant = name
+          name     = :default
+        end
+
+        is_instance = !(constant.kind_of?(Class) || dsl_block) # i don't like this magic too much, but since it's the only DSL method in TRB, it should be ok. # DISCUSS: options[:is_instance]
+
+        path = path_name(options[:prefix], name, is_instance ? nil : "class") # "contract.default.class"
+
+        if is_instance
+          skill = constant
+        else
+          extended = options[:container][path] # Operation["contract.default.class"]
+          extended = yield extended if extended && block_given?
+
+          # only extend an existing skill class when NO constant was passed.
+          constant = (extended || options[:class]) if constant.nil?# && block_given?
+
+          skill = Class.new(constant)
+          skill.class_eval(&dsl_block) if dsl_block
+        end
+
+        [path, skill]
+      end
+
+    private
+      def path_name(prefix, name, suffix)
+        [prefix, name, suffix].compact.join(".") # "contract.class" for default, otherwise "contract.params.class" etc.
+      end
+    end
+  end
+end