trailblazer-operation 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00f1e4d05147c0c9434d2a72017c7ea452cd06a5bf5e90985f7f809f5246ac9b
-  data.tar.gz: 6508179d1158e4719f90e7e6a219676b47780468d99f58b6c4178f423415f6ca
+  metadata.gz: 318d6a14d3ed10922cd2b8a2ec9d67f3d73672488c4833ddfa883ab13c382fe3
+  data.tar.gz: 3432c41d2f36efa9f313f2da68195dfab92b486881db581c03430955202c188b
 SHA512:
-  metadata.gz: bc578ee53cf1f1ecbef264943841734cb250902c329f7866eec533553e720c58ac1d5f8edf3bf84405a138aa37f25a7abf01153458ce3d177833fe0e51f83801
-  data.tar.gz: b1972a63eddccb14fb5814c0e973543757feb56d62a0400be18da49ef8c0ca3ddda40aaef8d28983177783a48aa2345b8d86f4eaf52a43a098638956914ef60c
+  metadata.gz: 9d53cc20604c0e11912e4822ce0ab6cc5f05da4a7f7a4cc688da2d350bf859a2e7863f36324bd2c1015ec3ed38118f9ad0e6dcd424229552c0ad6853f760f0af
+  data.tar.gz: e897df0be7f3530c8f8f826ace7db4e0255ce055bda7cbdae995596d91cad2bdd19cbd21f6b2645507ef4a4b7dd71896c94ca78ab4d75960f8ef23bff2a10ba1

data/.github/workflows/ci.yml

@@ -5,10 +5,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.5, 2.6, 2.7, '3.0', '3.1', '3.2', 'jruby']
+        ruby: [2.5, 2.6, 2.7, '3.0', '3.1', '3.2', "3.3", 'jruby']
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}

data/CHANGES.md

@@ -1,3 +1,13 @@
+## 0.11.0
+
+* Introduce `Operation.call_with_public_interface_from_call` which merges `ctx` and `circuit_options`
+  accordingly, so the overrider of `Operation.call_with_public_interface` gets correct args.
+* Removing `Operation.trace`, you've been warned! Use `Operation.wtf?`. This also removes `Result#wtf`.
+  See [https://github.com/trailblazer/trailblazer-operation/blob/3f821c7d576e7ccccf580fbd8c9305501fdc5d2c/test/trace_test.rb#L22](this sample test case)
+  if you need a more low-level interface to tracing.
+* No need to pass `:exec_context` in `#call_with_public_interface`. This is  done in `Strategy.call`.
+* Rename `Result#event` to `Result#terminus` for consistency. Deprecate `Result#event`.
+
 ## 0.10.1
 
 * Deprecate `Operation.trace` and `Result#wtf?` in favor of `Operation.wtf?`.

data/lib/trailblazer/operation/class_dependencies.rb

@@ -25,7 +25,7 @@ class Trailblazer::Operation
     end
 
     private def context_for_fields(fields, (ctx, flow_options), **)
-      ctx_with_fields = Trailblazer::Context(fields, ctx, flow_options[:context_options]) # TODO: redundant to options_for_public_call.
+      _ctx_with_fields = Trailblazer::Context(fields, ctx, flow_options[:context_options]) # TODO: redundant to options_for_public_call.
     end
 
     def call_with_circuit_interface((ctx, flow_options), **circuit_options)

data/lib/trailblazer/operation/public_call.rb

@@ -16,7 +16,16 @@ module Trailblazer
     def call(options = {}, flow_options = {}, **circuit_options)
       return call_with_circuit_interface(options, **circuit_options) if options.is_a?(Array) # This is kind of a hack that could be well hidden if Ruby had method overloading. Goal is to simplify the call thing as we're fading out Operation::public_call anyway.
 
-      call_with_public_interface(options, flow_options, **circuit_options)
+      call_with_public_interface_from_call(options, flow_options, **circuit_options)
+    end
+
+    # @private Please do not override this method as it might get removed.
+    def call_with_public_interface_from_call(options, flow_options, **circuit_options)
+      # normalize options.
+      options = options
+        .merge(circuit_options) # when using Op.call(params:, ...), {circuit_options} will always be ctx variables.
+
+      call_with_public_interface(options, flow_options)
     end
 
     # Default {@activity} call interface which doesn't accept {circuit_options}
@@ -25,24 +34,19 @@ module Trailblazer
     #
     # @return [Operation::Railway::Result]
     #
-    # @private
+    # @semi-public It's OK to override this method.
     def call_with_public_interface(options, flow_options, invoke_class: Activity::TaskWrap, **circuit_options)
       flow_options  = flow_options_for_public_call(flow_options)
-
-      # In Ruby < 3, calling Op.(params: {}, "current_user" => user) results in both {circuit_options} and {options} containing variables.
-      # In Ruby 3.0, **circuit_options is always empty.
-      options       = circuit_options.any? ? circuit_options.merge(options) : options
-
       ctx           = options_for_public_call(options, flow_options)
 
-      # call the activity.
-      # This will result in invoking {::call_with_circuit_interface}.
+      # Call the activity as it if was a step in an endpoint.
+
+      # This will result in invoking {self.call_with_circuit_interface}.
       signal, (ctx, flow_options) = invoke_class.invoke(
         self,
         [ctx, flow_options],
-        exec_context: new,
-        # wrap_static: initial_wrap_static,
-        container_activity: Activity::TaskWrap.container_activity_for(self, wrap_static: initial_wrap_static)
+        container_activity: Activity::TaskWrap.container_activity_for(self, wrap_static: initial_wrap_static), # we cannot make this static because of {self} unless we override {#inherited}.
+        **circuit_options # this will always be an empty hash if coming from #{call_with_public_interface_from_call}.
       )
 
       # Result is successful if the activity ended with an End event derived from Railway::End::Success.
@@ -83,15 +87,21 @@ module Trailblazer
       call_with_public_interface(options, flow_options, {invoke_class: Activity::TaskWrap})
     end
 
+    # This TaskWrap step replaces the default {call_task} step for this very operation.
+    # Instead of invoking the operation using {Operation.call}, it does {Operation.call_with_circuit_interface},
+    # so we don't invoke {Operation.call} twice.
+    #
+    # I don't really like this "hack", but it's the only way until we get method overloading.
+    #
     # @private
     def self.call_task(wrap_ctx, original_args) # DISCUSS: copied from {TaskWrap.call_task}.
-      op = wrap_ctx[:task]
+      operation = wrap_ctx[:task]
 
       original_arguments, original_circuit_options = original_args
 
       # Call the actual task we're wrapping here.
       # puts "~~~~wrap.call: #{task}"
-      return_signal, return_args = op.call_with_circuit_interface(original_arguments, **original_circuit_options)
+      return_signal, return_args = operation.call_with_circuit_interface(original_arguments, **original_circuit_options)
 
       # DISCUSS: do we want original_args here to be passed on, or the "effective" return_args which are different to original_args now?
       wrap_ctx = wrap_ctx.merge(return_signal: return_signal, return_args: return_args)

data/lib/trailblazer/operation/railway.rb

@@ -10,20 +10,26 @@ module Trailblazer
       def self.fail_fast!; Activity::FastTrack::FailFast end
       def self.pass_fast!; Activity::FastTrack::PassFast end
       # @param options Context
-      # @param end_event The last emitted signal in a circuit is usually the end event.
-      def self.Result(end_event, options, *)
-        Result.new(end_event.kind_of?(End::Success), options, end_event)
+      # @param terminus The last emitted signal in a circuit is the end event/terminus.
+      def self.Result(terminus, options, *)
+        Result.new(terminus.kind_of?(End::Success), options, terminus)
       end
 
-      # The Railway::Result knows about its binary state, the context (data), and the last event in the circuit.
+      # The Railway::Result knows about its binary state, the context (data), and
+      # the reached terminus of the circuit.
       class Result < Result # Operation::Result
-        def initialize(success, data, event)
+        def initialize(success, data, terminus)
           super(success, data)
 
-          @event = event
+          @terminus = terminus
         end
 
-        attr_reader :event
+        def event
+          Activity::Deprecate.warn caller_locations[0], %(Using `Result#event` is deprecated, please use `Result#terminus`)
+          terminus
+        end
+
+        attr_reader :terminus
       end
 
       module End

data/lib/trailblazer/operation/version.rb

@@ -1,7 +1,7 @@
 module Trailblazer
   module Version
     module Operation
-      VERSION = "0.10.1"
+      VERSION = "0.11.0"
     end
   end
 end

data/lib/trailblazer/operation/wtf.rb

@@ -0,0 +1,11 @@
+require "trailblazer/developer"
+
+module Trailblazer
+  class Operation
+    module Wtf
+      def wtf?(options)
+        call_with_public_interface(options, {}, invoke_class: Developer::Wtf)
+      end
+    end
+  end
+end

data/lib/trailblazer/operation.rb

@@ -50,8 +50,8 @@ module Trailblazer
     require "trailblazer/operation/public_call"      # TODO: Remove in 3.0.
     extend PublicCall              # ::call(params: .., current_user: ..)
 
-    require "trailblazer/operation/trace"
-    extend Trace                   # ::trace
+    require "trailblazer/operation/wtf"
+    extend Wtf                   # ::trace
   end
 end
 

data/test/call_test.rb

@@ -41,21 +41,22 @@ class CallTest < Minitest::Spec
     result.event.must_equal Update.to_h[:outputs].find { |output| output.semantic == :failure }.signal
   end
 
+  def self.add_1(wrap_ctx, original_args)
+    ctx, = original_args[0]
+    ctx[:seq] << 1
+    return wrap_ctx, original_args # yay to mutable state. not.
+  end
+
   it "invokes with the taskWrap" do
     operation = Class.new(Trailblazer::Operation) do
       include Trailblazer::Activity::Testing.def_steps(:a)
 
-      def self.add_1(wrap_ctx, original_args)
-        ctx, = original_args[0]
-        ctx[:seq] << 1
-        return wrap_ctx, original_args # yay to mutable state. not.
-      end
-
       merge = [
-        [Trailblazer::Activity::TaskWrap::Pipeline.method(:insert_before), "task_wrap.call_task", ["user.add_1", method(:add_1)]]
       ]
 
-      step :a, extensions: [Trailblazer::Activity::TaskWrap::Extension(merge: merge)]
+      step :a, extensions: [Trailblazer::Activity::TaskWrap::Extension.WrapStatic(
+          [CallTest.method(:add_1), prepend: "task_wrap.call_task", id: "user.add_1"]
+        )]
     end
 
     # normal operation invocation
@@ -64,10 +65,31 @@ class CallTest < Minitest::Spec
     result.inspect(:seq).must_equal %{<Result:true [[1, :a]] >}
 
     # with tracing
-    result = operation.trace(seq: [])
+    result = operation.wtf?(seq: [])
 
     result.inspect(:seq).must_equal %{<Result:true [[1, :a]] >}
+  end
+
+
+  it "calls with the taskWrap defined for operation using circuit interface" do
+    operation = Class.new(Trailblazer::Operation) do
+      include Trailblazer::Activity::Testing.def_steps(:a)
+
+      step :a
+    end
+
+    my_extension = Trailblazer::Activity::TaskWrap::Extension(
+      [CallTest.method(:add_1), id: "my.add_1", append: "task_wrap.call_task"]
+    )
+
+    # circuit interface invocation using call
+    signal, (ctx, _) = operation.call(
+      [{seq: []}, {}],
+      wrap_runtime: Hash.new(my_extension),
+      runner: Trailblazer::Activity::TaskWrap::Runner
+    )
 
-    result.wtf?
+    assert_equal signal.to_h[:semantic], :success
+    assert_equal ctx[:seq], [1, :a, 1, 1]
   end
 end

data/test/class_dependencies_test.rb

@@ -28,10 +28,14 @@ class ClassDependenciesTest < Minitest::Spec
     end
 
     # "model.class" gets injected automatically just before {Index}.
-    Home.({params: {}}).inspect.must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Module} mutable_options=#<Trailblazer::Context::Container wrapped_options={:params=>{}} mutable_options={\"a\"=>Module}>> >}
+    result = Home.({params: {}})
+    assert_result result, {:"model.class"=>Module, :params=>{}, :a=>Module}
+    # .inspect.must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Module} mutable_options=#<Trailblazer::Context::Container wrapped_options={:params=>{}} mutable_options={\"a\"=>Module}>> >}
 
     # "model.class" gets injected by user and overrides class dependencies.
-    Home.({params: {}, "model.class" => Symbol}).inspect.must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Module} mutable_options=#<Trailblazer::Context::Container wrapped_options={:params=>{}, \"model.class\"=>Symbol} mutable_options={\"a\"=>Symbol}>> >}
+    result = Home.({params: {}, "model.class" => Symbol})
+    assert_result result, {:"model.class"=>Symbol, :params=>{}, :a=>Symbol  }
+    # .inspect.must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Module} mutable_options=#<Trailblazer::Context::Container wrapped_options={:params=>{}, \"model.class\"=>Symbol} mutable_options={\"a\"=>Symbol}>> >}
 
 
     class Dashboard < Trailblazer::Operation
@@ -43,8 +47,8 @@ class ClassDependenciesTest < Minitest::Spec
     end
 
   # TODO: "model.class" gets injected automatically in {Dashboard} and overrides the {Index} input.
-    Dashboard.({params: {}}).inspect.must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Module} mutable_options=#<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Float} mutable_options=#<Trailblazer::Context::Container wrapped_options={\"model.class\"=>Float} mutable_options=#<Trailblazer::Context::Container wrapped_options={:params=>{}} mutable_options={:Dashboard=>Float, \"a\"=>Float}>>>> >}
-
+    assert_equal Dashboard.({params: {}}).inspect,
+          %(<Result:true #<Trailblazer::Context::Container wrapped_options=#{{"model.class" => Module}} mutable_options=#<Trailblazer::Context::Container wrapped_options=#{{"model.class" => Float}} mutable_options=#<Trailblazer::Context::Container wrapped_options=#{{"model.class" => Float}} mutable_options=#<Trailblazer::Context::Container wrapped_options=#{{:params => {}}} mutable_options=#{{:Dashboard => Float, "a" => Float}}>>>> >)
   end
 
   describe "inheritance" do

data/test/docs/autogenerated/activity_basics_test.rb

@@ -0,0 +1,72 @@
+# THIS FILE IS AUTOGENERATED FROM trailblazer-activity-dsl-linear/test/docs/activity_basics_test.rb
+require "test_helper"
+
+module X
+  class DocsActivityTest < Minitest::Spec
+    it "basic activity" do
+      Memo = Struct.new(:options) do
+        def save
+          true
+        end
+      end
+
+      #:memo-create
+      module Memo::Operation
+        class Create < Trailblazer::Operation
+          step :validate
+          #~body
+          step :save
+          left :handle_errors
+          step :notify
+          #~meths
+          include T.def_steps(:validate, :save, :handle_errors, :notify)
+
+          #:save
+          def save(ctx, params:, **)
+            memo = Memo.new(params[:memo])
+            memo.save
+
+            ctx[:model] = memo # you can write to the {ctx}.
+          end
+          #:save end
+
+          def notify(ctx, **)
+            true
+          end
+
+          #~body end
+          def validate(ctx, params:, **) # home-made validation
+            params.key?(:memo) &&
+            params[:memo].key?(:text) &&
+            params[:memo][:text].size > 9
+            # return value matters!
+          end
+          #~meths end
+        end
+      end
+      #:memo-create end
+
+      #:memo-call
+      result = Memo::Operation::Create.(
+        params: {memo: {text: "Do not forget!"}}
+      )
+
+      result.success? # => true
+      puts result.terminus.to_h[:semantic] #=> :success
+      #:memo-call end
+
+      #:memo-call-model
+      result = Memo::Operation::Create.(
+        params: {memo: {text: "Do not forget!"}}
+      )
+
+      #~ctx_to_result
+      puts result[:model] #=> #<Memo id: 1 text: "Do not forget!">
+      #:memo-call-model end
+      #~ctx_to_result end
+
+      assert_equal result.terminus.inspect, %(#<Trailblazer::Activity::Railway::End::Success semantic=:success>)
+      #~ignore end
+    end
+  end
+end