trailblazer-future 2.1.0.rc1

data/lib/trailblazer/v2_1/macro.rb

@@ -0,0 +1,11 @@
+require "trailblazer/v2_1/operation"
+
+require "trailblazer/v2_1/operation/inject"
+
+require "trailblazer/v2_1/operation/model"
+require "trailblazer/v2_1/operation/policy"
+require "trailblazer/v2_1/operation/guard"
+require "trailblazer/v2_1/operation/pundit"
+require "trailblazer/v2_1/operation/nested"
+require "trailblazer/v2_1/operation/rescue"
+require "trailblazer/v2_1/operation/wrap"

data/lib/trailblazer/v2_1/macro/contract.rb

@@ -0,0 +1,5 @@
+require "reform"
+require "trailblazer/v2_1/operation"
+require "trailblazer/v2_1/operation/contract"
+require "trailblazer/v2_1/operation/validate"
+require "trailblazer/v2_1/operation/persist"

data/lib/trailblazer/v2_1/operation.rb

@@ -0,0 +1,91 @@
+require "forwardable"
+
+# trailblazer-context
+require "trailblazer/v2_1/option"
+require "trailblazer/v2_1/context"
+require "trailblazer/v2_1/container_chain"
+
+require "trailblazer/v2_1/activity"
+require "trailblazer/v2_1/activity/dsl/magnetic"
+
+
+require "trailblazer/v2_1/operation/callable"
+
+require "trailblazer/v2_1/operation/heritage"
+require "trailblazer/v2_1/operation/public_call"      # TODO: Remove in 3.0.
+require "trailblazer/v2_1/operation/class_dependencies"
+require "trailblazer/v2_1/operation/deprecated_macro" # TODO: remove in 2.2.
+require "trailblazer/v2_1/operation/result"
+require "trailblazer/v2_1/operation/railway"
+
+require "trailblazer/v2_1/operation/railway/fast_track"
+require "trailblazer/v2_1/operation/railway/normalizer"
+require "trailblazer/v2_1/operation/trace"
+
+require "trailblazer/v2_1/operation/railway/macaroni"
+
+module Trailblazer::V2_1
+  # The Trailblazer::V2_1-style operation.
+  # Note that you don't have to use our "opinionated" version with result object, skills, etc.
+  class Operation
+
+    module FastTrackActivity
+      builder_options = {
+        track_end:     Railway::End::Success.new(semantic: :success),
+        failure_end:   Railway::End::Failure.new(semantic: :failure),
+        pass_fast_end: Railway::End::PassFast.new(semantic: :pass_fast),
+        fail_fast_end: Railway::End::FailFast.new(semantic: :fail_fast),
+      }
+
+      extend Activity::FastTrack( pipeline: Railway::Normalizer::Pipeline, builder_options: builder_options )
+    end
+
+    extend Skill::Accessors        # ::[] and ::[]= # TODO: fade out this usage.
+
+    def self.inherited(subclass)
+      super
+      subclass.initialize!
+      heritage.(subclass)
+    end
+
+    def self.initialize!
+      @activity = FastTrackActivity.clone
+    end
+
+
+    extend Activity::Interface
+
+    module Process
+      def to_h
+        @activity.to_h.merge( activity: @activity )
+      end
+    end
+
+    extend Process # make ::call etc. class methods on Operation.
+
+    extend Heritage::Accessor
+
+    class << self
+      extend Forwardable # TODO: test those helpers
+      def_delegators :@activity, :Path, :Output, :End, :Track
+      def_delegators :@activity, :outputs
+
+      def step(task, options={}, &block); add_task!(:step, task, options, &block) end
+      def pass(task, options={}, &block); add_task!(:pass, task, options, &block) end
+      def fail(task, options={}, &block); add_task!(:fail, task, options, &block) end
+
+      alias_method :success, :pass
+      alias_method :failure, :fail
+
+      def add_task!(name, task, options, &block)
+        heritage.record(name, task, options, &block)
+        @activity.send(name, task, options, &block)
+      end
+    end
+
+    extend PublicCall              # ::call(params, { current_user: .. })
+    extend Trace                   # ::trace
+  end
+end
+
+require "trailblazer/v2_1/operation/inspect"

data/lib/trailblazer/v2_1/operation/auto_inject.rb

@@ -0,0 +1,47 @@
+require "dry/auto_inject"
+
+class Trailblazer::V2_1::Operation
+  # Thanks, @timriley! <3
+  # https://gist.github.com/timriley/d314a58da9784912159006e208ba8ea9
+  module AutoInject
+    class InjectStrategy < Module
+      ClassMethods = Class.new(Module)
+
+      attr_reader :container
+      attr_reader :dependency_map
+      attr_reader :class_mod
+
+      def initialize(container, *dependency_names)
+        @container = container
+        @dependency_map = Dry::AutoInject::DependencyMap.new(*dependency_names)
+        @class_mod = ClassMethods.new
+      end
+
+      def included(klass)
+        define_call
+
+        klass.singleton_class.prepend @class_mod
+
+        super
+      end
+
+      private
+
+      def define_call
+        class_mod.class_exec(container, dependency_map) do |container, dependency_map|
+          define_method :call_with_public_interface do |ctx={}, *dependencies|
+            ctx_with_deps = dependency_map.to_h.each_with_object({}) { |(name, identifier), obj|
+              obj[name] = ctx[name] || container[identifier]
+            }.merge(ctx)
+
+            super(ctx_with_deps, *dependencies)
+          end
+        end
+      end
+    end
+  end
+
+  def self.AutoInject(container)
+    Dry::AutoInject(container, strategies: {default: AutoInject::InjectStrategy})
+  end
+end

data/lib/trailblazer/v2_1/operation/callable.rb

@@ -0,0 +1,42 @@
+module Trailblazer::V2_1
+  class Operation
+    # Use {Callable} if you have an operation or any other callable object that does
+    # _not_ expose an {Activity interface}. For example, {Operation.call} isn't compatible
+    # with activities, hence you need to decorate it using {Callable}. The returned object
+    # exposes an {Activity interface}.
+    #
+    # @param :call [Symbol] Method name to call
+    # @param options [Hash] Hash to merge into {circuit_options}, e.g. {:start_task}.
+    #
+    # @example Create and use a Callable instance.
+    #   callable = Trailblazer::V2_1::Operation::Callable( Memo::Create, call: :__call__ )
+    #   callable.( [ctx, {}] ) #=> Activity interface, ::call will invoke Memo::Create.__call__.
+    def self.Callable(*args)
+      Callable.new(*args)
+    end
+
+    # Subprocess allows to have tasks with a different call interface and start event.
+    # @param activity any object with an {Activity interface}
+    class Callable
+      include Activity::Interface
+
+      def initialize(activity, call: :call, **options)
+        @activity = activity
+        @options  = options
+        @call     = call
+      end
+
+      def call(args, **circuit_options)
+        @activity.public_send(@call, args, circuit_options.merge(@options))
+      end
+
+      extend Forwardable
+      # @private
+      def_delegators :@activity, :to_h, :debug
+
+      def to_s
+        %{#<Trailblazer::V2_1::Activity::Callable activity=#{@activity}>}
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/class_dependencies.rb

@@ -0,0 +1,25 @@
+# Dependencies can be defined on the operation. class level
+class Trailblazer::V2_1::Operation
+  module Skill
+    # The class-level skill container: Operation::[], ::[]=.
+    module Accessors
+      # :private:
+      def skills
+        @skills ||= {}
+      end
+
+      extend Forwardable
+      def_delegators :skills, :[], :[]=
+    end
+  end
+
+  # The use of this module is not encouraged and it is only here for backward-compatibility.
+  # Instead, please pass dependencies via containers, locals, or macros into the respective steps.
+  module ClassDependencies
+    def call_with_circuit_interface( (ctx, flow_options), **circuit_options )
+      @skills.each { |name, value| ctx[name] ||= value } # this resembles the behavior in 2.0. we didn't say we liked it.
+
+      super
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/contract.rb

@@ -0,0 +1,61 @@
+module Trailblazer::V2_1
+  class Operation
+    module Contract
+      def self.Build(name: "default", constant: nil, builder: nil)
+        task = lambda do |(options, flow_options), **circuit_options|
+          result = Build.(options, circuit_options, name: name, constant: constant, builder: builder)
+
+          return Activity::TaskBuilder.binary_signal_for( result, Activity::Right, Activity::Left ),
+              [options, flow_options]
+        end
+
+        { task: task, id: "contract.build" }
+      end
+
+      module Build
+        # Build contract at runtime.
+        def self.call(options, circuit_options, name: "default", constant: nil, builder: nil)
+          # TODO: we could probably clean this up a bit at some point.
+          contract_class = constant || options["contract.#{name}.class"] # DISCUSS: Injection possible here?
+          model          = options[:model]
+          name           = "contract.#{name}"
+
+          options[name] =
+            if builder
+              call_builder( options, circuit_options, builder: builder, constant: contract_class, name: name )
+            else
+              contract_class.new(model)
+            end
+        end
+
+        def self.call_builder(options, circuit_options, builder:raise, constant:raise, name:raise)
+          tmp_options = options.to_hash.merge(
+            constant: constant,
+            name:     name
+          )
+          Trailblazer::V2_1::Option(builder).( options, tmp_options, circuit_options )
+        end
+      end
+
+      module DSL
+        def self.extended(extender)
+          extender.extend(ClassDependencies)
+          warn "[Trailblazer::V2_1] Using `contract do...end` is deprecated. Please use a form class and the Builder( constant: <Form> ) option."
+        end
+
+        # This is the class level DSL method.
+        #   Op.contract #=> returns contract class
+        #   Op.contract do .. end # defines contract
+        #   Op.contract CommentForm # copies (and subclasses) external contract.
+        #   Op.contract CommentForm do .. end # copies and extends contract.
+        def contract(name=:default, constant=nil, base: Reform::Form, &block)
+          heritage.record(:contract, name, constant, &block)
+
+          path, form_class = Trailblazer::V2_1::DSL::Build.new.({ prefix: :contract, class: base, container: self }, name, constant, block)
+
+          self[path] = form_class
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/deprecated_macro.rb

@@ -0,0 +1,19 @@
+# TODO: REMOVE IN 2.2.
+module Trailblazer::V2_1
+  module Operation::DeprecatedMacro
+    # Allows old macros with the `(input, options)` signature.
+    def self.call(proc, options)
+      warn %{[Trailblazer::V2_1] Macros with API (input, options) are deprecated. Please use the "Task API" signature (options, flow_options) or use a simpler Callable. (#{proc})}
+
+      wrapped_proc = ->( (options, flow_options), **circuit_options ) do
+        result = proc.(circuit_options[:exec_context], options) # run the macro, with the deprecated signature.
+
+        direction = Activity::TaskBuilder.binary_signal_for(result, Activity::Right, Activity::Left)
+
+        return direction, [options, flow_options]
+      end
+
+      options.merge( task: wrapped_proc )
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/deprecations.rb

@@ -0,0 +1,21 @@
+module Trailblazer::V2_1
+  class Operation
+    class DeprecatedOptions < Option
+      def self.call!(proc, direction, options, flow_options, *args)
+        if proc.is_a?(Proc) && proc.arity == 1
+          deprecate(proc)
+          proc.(options)
+        elsif proc.method(:call).arity == 1
+          deprecate(proc)
+          proc.(options)
+        else
+          super
+        end
+      end
+
+      def self.deprecate(proc)
+        warn "[Trailblazer::V2_1] Please use the step API `def my_step!(options, **)` for your step: #{proc}"
+      end
+    end # DeprecatedOptions
+  end
+end

data/lib/trailblazer/v2_1/operation/guard.rb

@@ -0,0 +1,18 @@
+class Trailblazer::V2_1::Operation
+  module Policy
+    def self.Guard(proc, name: :default, &block)
+      Policy.step( Guard.build(proc), name: name )
+    end
+
+    module Guard
+      def self.build(callable)
+        option = Trailblazer::V2_1::Option::KW(callable)
+
+        # this gets wrapped in a Operation::Result object.
+        ->( (options, *), circuit_args ) do
+          Result.new(!!option.call(options, circuit_args), {})
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/heritage.rb

@@ -0,0 +1,30 @@
+module Trailblazer::V2_1
+  # This is copied from the Declarative gem. This might get removed in favor of a real heritage gem.
+  class Operation
+    class Heritage < Array
+      # Record inheritable assignments for replay in an inheriting class.
+      def record(method, *args, &block)
+        self << { method: method, args: args, block: block }
+      end
+
+      # Replay the recorded assignments on inheritor.
+      # Accepts a block that will allow processing the arguments for every recorded statement.
+      def call(inheritor, &block)
+        each { |cfg| call!(inheritor, cfg, &block) }
+      end
+
+    private
+      def call!(inheritor, cfg)
+        yield cfg if block_given? # allow messing around with recorded arguments.
+
+        inheritor.send(cfg[:method], *cfg[:args], &cfg[:block])
+      end
+
+      module Accessor
+        def heritage
+          @heritage ||= Heritage.new
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/inject.rb

@@ -0,0 +1,36 @@
+module Trailblazer::V2_1
+  module Operation::Wrap
+    module Inject
+      # Returns an Alteration wirings that, when applied, inserts the {ReverseMergeDefaults} task
+      # before the {Wrap::Call} task. This is meant for macros and steps that accept a dependency
+      # injection but need a default parameter to be set if not injected.
+      # @returns ADDS
+      def self.Defaults(default_dependencies)
+        Module.new do
+          extend Activity::Path::Plan()
+
+          task ReverseMergeDefaults.new( default_dependencies ),
+            id:     "ReverseMergeDefaults#{default_dependencies}",
+            before: "task_wrap.call_task"
+        end
+      end
+
+      # @api private
+      # @returns Task
+      # @param Hash list of key/value that should be set if not already assigned/set before (or injected from the outside).
+      class ReverseMergeDefaults
+        def initialize(defaults)
+          @defaults = defaults
+        end
+
+        def call((wrap_ctx, original_args), **circuit_options)
+          ctx = original_args[0][0]
+
+          @defaults.each { |k, v| ctx[k] ||= v }
+
+          return Activity::Right, [ wrap_ctx, original_args ]
+        end
+      end
+    end # Inject
+  end
+end

data/lib/trailblazer/v2_1/operation/inspect.rb

@@ -0,0 +1,79 @@
+module Trailblazer::V2_1
+  # Operation-specific circuit rendering. This is optimized for a linear railway circuit.
+  #
+  # @private
+  #
+  # NOTE: this is absolutely to be considered as prototyping and acts more like a test helper ATM as
+  # Inspect is not a mission-critical part.
+  class Operation
+    def self.introspect(*args)
+      Operation::Inspect.(*args)
+    end
+  end
+
+  module Operation::Inspect
+    module_function
+
+    def call(operation, options={ style: :line })
+      # TODO: better introspection API.
+
+      alterations = Activity::Magnetic::Builder::Finalizer.adds_to_alterations(operation.to_h[:adds])
+      # DISCUSS: any other way to retrieve the Alterations?
+
+      # pp alterations
+      railway = alterations.instance_variable_get(:@groups).instance_variable_get(:@groups)[:main]
+
+      rows = railway.each_with_index.collect do |element, i|
+        magnetic_to, task, plus_poles = element.configuration
+
+        created_by =
+          if magnetic_to == [:failure]
+            :fail
+          elsif plus_poles.size > 1
+            plus_poles[0].color == plus_poles[1].color ? :pass : :step
+          else
+            :pass # this is wrong for Nested, sometimes
+          end
+
+        [ i, [ created_by, element.id ] ]
+      end
+
+      return inspect_line(rows) if options[:style] == :line
+      return inspect_rows(rows)
+    end
+
+    def inspect_func(step)
+      @inspect[step]
+    end
+
+    Operator = { :fail => "<<", :pass => ">>", :step => ">"}
+
+    def inspect_line(names)
+      string = names.collect { |i, (end_of_edge, name)| "#{Operator[end_of_edge]}#{name}" }.join(",")
+      "[#{string}]"
+    end
+
+    def inspect_rows(names)
+      string = names.collect do |i, (end_of_edge, name)|
+        operator = Operator[end_of_edge]
+
+        op = "#{operator}#{name}"
+        padding = 38
+
+        proc = if operator == "<<"
+          sprintf("%- #{padding}s", op)
+        elsif [">", ">>", "&"].include?(operator.to_s)
+          sprintf("% #{padding}s", op)
+        else
+          pad = " " * ((padding - op.length) / 2)
+          "#{pad}#{op}#{pad}"
+        end
+
+        proc = proc.gsub(" ", "=")
+
+        sprintf("%2d %s", i, proc)
+      end.join("\n")
+      "\n#{string}"
+    end
+  end
+end