trailblazer-future 2.1.0.rc1

data/lib/trailblazer/v2_1/operation/railway/task_builder.rb

@@ -0,0 +1,37 @@
+module Trailblazer::V2_1
+  module Operation::Railway
+    # every step is wrapped by this proc/decider. this is executed in the circuit as the actual task.
+    # Step calls step.(options, **options, flow_options)
+    # Output direction binary: true=>Right, false=>Left.
+    # Passes through all subclasses of Direction.~~~~~~~~~~~~~~~~~
+    module TaskBuilder
+      def self.call(user_proc)
+        Task.new( Trailblazer::V2_1::Option::KW( user_proc ), user_proc )
+      end
+
+      # Translates the return value of the user step into a valid signal.
+      # Note that it passes through subclasses of {Signal}.
+      def self.binary_direction_for(result, on_true, on_false)
+        result.is_a?(Class) && result < Activity::Signal ? result : (result ? on_true : on_false)
+      end
+    end
+
+    class Task
+      def initialize(task, user_proc)
+        @task      = task
+        @user_proc = user_proc
+        freeze
+      end
+
+      def call( (options, *args), **circuit_args )
+        # Execute the user step with TRB's kw args.
+        result = @task.( options, **circuit_args ) # circuit_args contains :exec_context.
+
+        # Return an appropriate signal which direction to go next.
+        direction = TaskBuilder.binary_direction_for( result, Activity::Right, Activity::Left )
+
+        [ direction, [ options, *args ], **circuit_args ]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+class Trailblazer::V2_1::Operation
+  NoopHandler = lambda { |*| }
+
+  def self.Rescue(*exceptions, handler: NoopHandler, &block)
+    exceptions = [StandardError] unless exceptions.any?
+
+    handler    = Rescue.deprecate_positional_handler_signature(handler)
+    handler    = Trailblazer::V2_1::Option(handler)
+
+    # This block is evaluated by {Wrap}.
+    rescue_block = ->((ctx, flow_options), **circuit_options, &nested_activity) do
+      begin
+        nested_activity.call
+      rescue *exceptions => exception
+        # DISCUSS: should we deprecate this signature and rather apply the Task API here?
+        handler.call(exception, ctx, **circuit_options) # FIXME: when there's an error here, it shows the wrong exception!
+
+        [ Trailblazer::V2_1::Operation::Railway.fail!, [ctx, flow_options] ]
+      end
+    end
+
+    Wrap( rescue_block, id: "Rescue(#{rand(100)})", &block )
+    # FIXME: name
+    # [ step, name: "Rescue:#{block.source_location.last}" ]
+  end
+
+  # TODO: remove me in 2.2.
+  module Rescue
+    def self.deprecate_positional_handler_signature(handler)
+      return handler if handler.is_a?(Symbol) # can't do nutting about this.
+
+      arity = handler.is_a?(Class) ? handler.method(:call).arity : handler.arity
+
+      return handler if arity != 2 # means (exception, (ctx, flow_options), *, &block), "new style"
+
+      ->(exception, (ctx, flow_options), **circuit_options, &block) do
+        warn "[Trailblazer::V2_1] Rescue handlers have a new signature: (exception, *, &block)"
+        handler.(exception, ctx, &block)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Trailblazer::V2_1::Operation::Responder
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def model_name
+      model_class.model_name
+    end
+  end
+
+  extend Forwardable
+  def_delegators :@model, :to_param, :destroyed?, :persisted?
+
+  def to_model
+    @model
+  end
+end

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

@@ -0,0 +1,30 @@
+class Trailblazer::V2_1::Operation
+  class Result
+    # @param success Boolean validity of the result object
+    # @param data Context
+    def initialize(success, data)
+      @success, @data = success, data
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      ! success?
+    end
+
+    extend Forwardable
+    def_delegators :@data, :[] # DISCUSS: make it a real delegator? see Nested.
+
+    # DISCUSS: the two methods below are more for testing.
+    def inspect(*slices)
+      return "<Result:#{success?} #{slice(*slices).inspect} >" if slices.any?
+      "<Result:#{success?} #{@data.inspect} >"
+    end
+
+    def slice(*keys)
+      keys.collect { |k| self[k] }
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Trailblazer::V2_1
+  module Test
+    module Run
+      # DISCUSS: use Endpoint here?
+      # DISCUSS: use Controller code here?
+      module_function
+      def run(operation_class, *args)
+        result = operation_class.(*args)
+
+        raise "[Trailblazer::V2_1] #{operation_class} wasn't run successfully. #{result.inspect}" if result.failure?
+
+        result
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module Trailblazer::V2_1
+  class Operation
+    module Trace
+      # @note The problem in this method is, we have redundancy with Operation::PublicCall
+      def self.call(operation, *args)
+        ctx = PublicCall.options_for_public_call(*args)   # redundant with PublicCall::call.
+
+        # Prepare the tracing-specific arguments. This is only run once for the entire circuit!
+        operation, *args = Trailblazer::V2_1::Activity::Trace.arguments_for_call( operation, [ctx, {}], {} )
+
+        last_signal, (ctx, flow_options) = Activity::TaskWrap.invoke(operation, *args )
+
+        result = Railway::Result(last_signal, ctx)    # redundant with PublicCall::call.
+
+        Result.new(result, flow_options[:stack].to_a)
+      end
+
+      # `Operation::trace` is included for simple tracing of the flow.
+      # It simply forwards all arguments to `Trace.call`.
+      #
+      # @public
+      #
+      #   Operation.trace(params, "current_user" => current_user).wtf
+      def trace(*args)
+        Trace.(self, *args)
+      end
+
+      # Presentation of the traced stack via the returned result object.
+      # This object is wrapped around the original result in {Trace.call}.
+      class Result < SimpleDelegator
+        def initialize(result, stack)
+          super(result)
+          @stack = stack
+        end
+
+        def wtf
+          Trailblazer::V2_1::Activity::Trace::Present.(@stack)
+        end
+
+        def wtf?
+          puts wtf
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Trailblazer::V2_1
+  class Operation
+    module Contract
+      # result.contract = {..}
+      # result.contract.errors = {..}
+      # Deviate to left track if optional key is not found in params.
+      # Deviate to left if validation result falsey.
+      def self.Validate(skip_extract: false, name: "default", representer: false, key: nil, constant: nil) # DISCUSS: should we introduce something like Validate::Deserializer?
+        params_path = "contract.#{name}.params" # extract_params! save extracted params here.
+
+        extract  = Validate::Extract.new( key: key, params_path: params_path ).freeze
+        validate = Validate.new( name: name, representer: representer, params_path: params_path, constant: constant ).freeze
+
+        # Build a simple Railway {Activity} for the internal flow.
+        activity = Module.new do
+          extend Activity::Railway(name: "Contract::Validate")
+
+          step extract,  id: "#{params_path}_extract", Activity::DSL.Output(:failure) => Activity::DSL.End(:extract_failure) unless skip_extract || representer
+          step validate, id: "contract.#{name}.call"
+        end
+
+        options = { task: activity, id: "contract.#{name}.validate", outputs: activity.outputs}
+
+        # Deviate End.extract_failure to the standard failure track as a default. This can be changed from the user side.
+        options = options.merge(Activity::DSL.Output(:extract_failure) => Activity::DSL.Track(:failure)) unless skip_extract
+
+        options
+      end
+
+      class Validate
+        # Task: extract the contract's input from params by reading `:key`.
+        class Extract
+          def initialize(key:nil, params_path:nil)
+            @key, @params_path = key, params_path
+          end
+
+          def call( ctx, params:, ** )
+            ctx[@params_path] = @key ? params[@key] : params
+          end
+        end
+
+        def initialize(name:"default", representer:false, params_path:nil, constant: nil)
+          @name, @representer, @params_path, @constant = name, representer, params_path, constant
+        end
+
+        # Task: Validates contract `:name`.
+        def call( ctx, ** )
+          validate!(
+            ctx,
+            representer: ctx["representer.#{@name}.class"] ||= @representer, # FIXME: maybe @representer should use DI.
+            params_path: @params_path
+          )
+        end
+
+        def validate!(options, representer:false, from: :document, params_path:nil)
+          path     = "contract.#{@name}"
+          contract = @constant || options[path]
+
+          # this is for 1.1-style compatibility and should be removed once we have Deserializer in place:
+          options["result.#{path}"] = result =
+            if representer
+              # use :document as the body and let the representer deserialize to the contract.
+              # this will be simplified once we have Deserializer.
+              # translates to contract.("{document: bla}") { MyRepresenter.new(contract).from_json .. }
+              contract.(options[from]) { |document| representer.new(contract).parse(document) }
+            else
+              # let Reform handle the deserialization.
+              contract.(options[params_path])
+            end
+
+          result.success?
+        end
+      end
+    end
+  end # Operation
+end

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

@@ -0,0 +1,83 @@
+class Trailblazer::V2_1::Operation
+  def self.Wrap(user_wrap, id: "Wrap/#{rand(100)}", &block)
+    operation_class = Wrap.create_operation(block)
+    wrapped         = Wrap::Wrapped.new(operation_class, user_wrap)
+
+    { task: wrapped, id: id, outputs: operation_class.outputs }
+  end
+
+  module Wrap
+    def self.create_operation(block)
+      Class.new( Nested.operation_class, &block ) # Usually resolves to Trailblazer::V2_1::Operation.
+    end
+
+    # behaves like an operation so it plays with Nested and simply calls the operation in the user-provided block.
+    class Wrapped #< Trailblazer::V2_1::Operation # FIXME: the inheritance is only to satisfy Nested( Wrapped.new )
+      include Trailblazer::V2_1::Activity::Interface
+
+      private def deprecate_positional_wrap_signature(user_wrap)
+        parameters = user_wrap.is_a?(Module) ? user_wrap.method(:call).parameters : user_wrap.parameters
+
+        return user_wrap if parameters[0] == [:req] # means ((ctx, flow_options), *, &block), "new style"
+
+        ->((ctx, flow_options), **circuit_options, &block) do
+          warn "[Trailblazer::V2_1] Wrap handlers have a new signature: ((ctx), *, &block)"
+          user_wrap.(ctx, &block)
+        end
+      end
+
+      def initialize(operation, user_wrap)
+        user_wrap = deprecate_positional_wrap_signature(user_wrap)
+
+        @operation  = operation
+        @user_wrap  = user_wrap
+
+        # Since in the user block, you can return Railway.pass! etc, we need to map
+        # those to the actual wrapped operation's end.
+        outputs           = @operation.outputs
+        @signal_to_output = {
+          Railway.pass!      => outputs[:success].signal,
+          Railway.fail!      => outputs[:failure].signal,
+          Railway.pass_fast! => outputs[:pass_fast].signal,
+          Railway.fail_fast! => outputs[:fail_fast].signal,
+          true               => outputs[:success].signal,
+          false              => outputs[:failure].signal,
+          nil                => outputs[:failure].signal,
+        }
+      end
+
+      def call( (ctx, flow_options), **circuit_options )
+        block_calling_wrapped = -> {
+          activity = @operation.to_h[:activity]
+
+          activity.( [ctx, flow_options], **circuit_options )
+        }
+
+        # call the user's Wrap {} block in the operation.
+        # This will invoke block_calling_wrapped above if the user block yields.
+        returned = @user_wrap.( [ctx, flow_options], **circuit_options, &block_calling_wrapped )
+
+        # {returned} can be
+        #   1. {circuit interface return} from the begin block, because the wrapped OP passed
+        #   2. {task interface return} because the user block returns "customized" signals, true of fale
+
+        if returned.is_a?(Array) # 1. {circuit interface return}, new style.
+          signal, (ctx, flow_options) = returned
+        else                     # 2. {task interface return}, only a signal (or true/false)
+          # TODO: deprecate this?
+          signal = returned
+        end
+
+        # Use the original {signal} if there's no mapping.
+        # This usually means signal is an End instance or a custom signal.
+        signal = @signal_to_output.fetch(signal, signal)
+
+        return signal, [ctx, flow_options]
+      end
+
+      def outputs
+        @operation.outputs
+      end
+    end
+  end # Wrap
+end

data/lib/trailblazer/v2_1/option.rb

@@ -0,0 +1,78 @@
+module Trailblazer::V2_1
+  # @note This might go to trailblazer-args along with `Context` at some point.
+  def self.Option(proc)
+    Option.build(Option, proc)
+  end
+
+  class Option
+    # Generic builder for a callable "option".
+    # @param call_implementation [Class, Module] implements the process of calling the proc
+    #   while passing arguments/options to it in a specific style (e.g. kw args, step interface).
+    # @return [Proc] when called, this proc will evaluate its option (at run-time).
+    def self.build(call_implementation, proc)
+      if proc.is_a? Symbol
+        ->(*args, &block) { call_implementation.evaluate_method(proc, *args, &block) }
+      else
+        ->(*args, &block) { call_implementation.evaluate_callable(proc, *args, &block) }
+      end
+    end
+
+    # A call implementation invoking `proc.(*args)` and plainly forwarding all arguments.
+    # Override this for your own step strategy (see KW#call!).
+    # @private
+    def self.call!(proc, *args, &block)
+      proc.(*args, &block)
+    end
+
+    # Note that both #evaluate_callable and #evaluate_method drop most of the args.
+    # If you need those, override this class.
+    # @private
+    def self.evaluate_callable(proc, *args, **flow_options, &block)
+      call!(proc, *args, &block)
+    end
+
+    # Make the context's instance method a "lambda" and reuse #call!.
+    # @private
+    def self.evaluate_method(proc, *args, exec_context:raise("No :exec_context given."), **flow_options, &block)
+      call!(exec_context.method(proc), *args, &block)
+    end
+
+    # Returns a {Proc} that, when called, invokes the `proc` argument with keyword arguments.
+    # This is known as "step (call) interface".
+    #
+    # This is commonly used by `Operation::step` to wrap the argument and make it
+    # callable in the circuit.
+    #
+    #   my_proc = ->(options, **kws) { options["i got called"] = true }
+    #   task    = Trailblazer::V2_1::Option::KW(my_proc)
+    #   task.(options = {})
+    #   options["i got called"] #=> true
+    #
+    # Alternatively, you can pass a symbol and an `:exec_context`.
+    #
+    #   my_proc = :some_method
+    #   task    = Trailblazer::V2_1::Option::KW(my_proc)
+    #
+    #   class A
+    #     def some_method(options, **kws)
+    #       options["i got called"] = true
+    #     end
+    #   end
+    #
+    #   task.(options = {}, exec_context: A.new)
+    #   options["i got called"] #=> true
+    def self.KW(proc)
+      Option.build(KW, proc)
+    end
+
+    # TODO: It would be cool if call! was typed and had `options SymbolizedHash` or something.
+    class KW < Option
+      # A different call implementation that calls `proc` with a "step interface".
+      #   your_code.(options, **options)
+      # @private
+      def self.call!(proc, options, *)
+        proc.(options, **options.to_hash) # Step interface: (options, **)
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/rails.rb

@@ -0,0 +1,12 @@
+require "trailblazer/v2_1/rails/version"
+
+module Trailblazer::V2_1
+  module Rails
+  end
+end
+
+require "trailblazer/v2_1/rails/controller"
+require "trailblazer/v2_1/rails/cell"
+require "trailblazer/v2_1/rails/form"
+require "trailblazer/v2_1/rails/railtie"
+require "trailblazer/v2_1"