trailblazer-operation 0.10.0 → 0.11.0

data/test/docs/developer_test.rb

@@ -0,0 +1,27 @@
+require "test_helper"
+
+class Wtf_DeveloperDocsTest < Minitest::Spec
+  Memo = Class.new
+  module Memo::Operation
+    class Create < Trailblazer::Operation
+      step :validate
+      step :save
+      left :handle_errors
+      step :notify
+      #~meths
+      include T.def_steps(:validate, :save, :handle_errors, :notify)
+      #~meths end
+    end
+  end
+
+  it "what" do
+    #:wtf
+    result = Memo::Operation::Create.wtf?(
+      #~meths
+      seq: [],
+      #~meths end
+      params: {memo: "remember me!"}
+    )
+    #:wtf end
+  end
+end

data/test/docs/public_call_monkeypatching_test.rb

@@ -0,0 +1,96 @@
+require "test_helper"
+
+class PublicCallMonkeypatchingTest < Minitest::Spec
+  #@ test overriding {Operation.call_with_public_interface}
+  #@
+  module AfterCall
+    def self.add_task_name(wrap_ctx, original_args)
+      (ctx, _flow_options), circuit_options = original_args
+
+      activity  = circuit_options[:activity] # currently running Activity.
+      task      = wrap_ctx[:task]            # the current "step".
+      task_id   = Trailblazer::Activity::Introspect.Nodes(activity, task: task).id
+
+      ctx[:seq] << task_id
+
+      return wrap_ctx, original_args # yay to mutable state. not.
+    end
+  end
+
+  it "overrides {call_with_public_interface} and allows injecting {circuit_options} and {flow_options} from the override" do
+    TaskWrapExtension = Trailblazer::Activity::TaskWrap::Extension(
+      [AfterCall.method(:add_task_name), id: "my.add_1", append: "task_wrap.call_task"]
+    )
+
+    module OperationExtensions
+      def call_with_public_interface(ctx, flow_options, **circuit_options)
+        super(
+          ctx,
+          flow_options.merge({}),
+          **circuit_options.merge(
+            wrap_runtime: Hash.new(TaskWrapExtension),
+            runner: Trailblazer::Activity::TaskWrap::Runner
+          )
+        )
+      end
+    end
+
+    operation = Class.new(Trailblazer::Operation) do
+      step :a
+
+      include Trailblazer::Activity::Testing.def_steps(:a)
+    end
+    operation.extend OperationExtensions # monkey-patch the "global" Operation.
+
+
+    # circuit interface invocation using call
+    result = operation.call(
+      seq: []
+    )
+
+    assert_equal result.success?, true
+    assert_equal result[:seq], ["Start.default", :a, :a, "End.success", nil] # {nil} because we don't have an ID for the actual operation.
+  end
+end
+
+class FlowOptionsMonkeypatching < Minitest::Spec
+  module App
+    FLOW_OPTIONS = {
+      context_options: {
+        aliases: { "contract.default": :contract },
+        container_class: Trailblazer::Context::Container::WithAliases,
+      }
+    }
+
+    module OperationExtensions
+      def call_with_public_interface(ctx, flow_options, **circuit_options)
+        super(
+          ctx,
+          flow_options.merge(App::FLOW_OPTIONS),
+          **circuit_options
+        )
+      end
+    end
+  end
+
+  it "inject aliases for the global run via {flow_options}" do
+    operation = Class.new(Trailblazer::Operation) do
+      step :a
+
+      def a(ctx, contract:, **)
+        ctx[:seq] << contract
+      end
+    end
+    operation.extend App::OperationExtensions # monkey-patch the "global" Operation.
+
+
+    # circuit interface invocation using call
+    result = operation.call(
+      seq: [],
+      :"contract.default" => Object,
+    )
+
+    assert_equal result.success?, true
+    assert_equal result[:seq].inspect, %([Object])
+  end
+end

data/test/docs/result_test.rb

@@ -0,0 +1,38 @@
+require "test_helper"
+
+module A
+  class DocsResultTest < Minitest::Spec
+    Memo = Class.new
+    module Memo::Operation
+      class Create < Trailblazer::Operation
+        step :validate, Output(:failure) => End(:validation_error)
+        step :save
+        include T.def_steps(:validate, :save)
+      end
+    end
+
+    it "exposes {#terminus}" do
+      result = Memo::Operation::Create.(seq: [])
+      assert_equal CU.inspect(result.terminus.to_h), %({:semantic=>:success})
+
+      result = Memo::Operation::Create.(validate: false, seq: [])
+      assert_equal CU.inspect(result.terminus.to_h), %({:semantic=>:validation_error})
+
+      result = Memo::Operation::Create.(save: false, seq: [])
+      assert_equal CU.inspect(result.terminus.to_h), %({:semantic=>:failure})
+    end
+
+    it "deprecates Result#event" do
+      result = Memo::Operation::Create.(seq: [])
+      terminus = nil
+
+      _, warning = capture_io do
+        terminus = result.event
+      end
+      line_no = __LINE__ - 2
+
+      assert_equal warning, %{[Trailblazer] #{File.realpath(__FILE__)}:#{line_no} Using `Result#event` is deprecated, please use `Result#terminus`\n}
+      assert_equal CU.inspect(terminus.to_h), %({:semantic=>:success})
+    end
+  end
+end

data/test/docs/step_dsl_test.rb

@@ -0,0 +1,93 @@
+require "test_helper"
+
+module A
+  class DocsStepTest < Minitest::Spec
+    Memo = Module.new
+
+    #:railway
+    module Memo::Operation
+      class Create < Trailblazer::Operation
+        step :validate
+        step :save
+        #~step
+        left :handle_errors
+        #~left
+        step :notify
+        #~meths
+        # fail :log_error
+        # step :save
+        def validate(ctx, params:, **)
+          ctx[:input] = Form.validate(params) # true/false
+        end
+
+        # def create(ctx, input:, create:, **)
+        #   create
+        # end
+
+        # def log_error(ctx, logger:, params:, **)
+        #   logger.error("wrong params: #{params.inspect}")
+        # end
+        #~meths end
+      end
+    end
+        #~step end
+        #~left end
+    #:railway end
+
+    # it "what" do
+    #   ctx = {params: {text: "Hydrate!"}, create: true}
+    #   signal, (ctx, _flow_options) = D::Create.([ctx, {}])
+    # end
+  end
+end
+
+
+module B
+  class Fail_DocsStepTest < Minitest::Spec
+    Memo = Module.new
+
+    #:fail
+    module Memo::Operation
+      class Create < Trailblazer::Operation
+        step :validate
+        step :save
+        fail :handle_errors # just like {#left}
+        #~meths
+        step :notify
+        include T.def_steps(:validate, :save, :handle_errors, :notify)
+        #~meths end
+      end
+    end
+    #:fail end
+
+    it "what" do
+      assert_invoke Memo::Operation::Create, seq: "[:validate, :save, :notify]"
+      assert_invoke Memo::Operation::Create, validate: false, terminus: :failure, seq: "[:validate, :handle_errors]"
+    end
+  end
+end
+
+module A
+  class Pass_DocsStepTest < Minitest::Spec
+    Memo = Module.new
+
+    #:pass
+    module Memo::Operation
+      class Create < Trailblazer::Operation
+        step :validate
+        pass :save # no output goes to the failure track here.
+        left :handle_errors
+        #~meths
+        step :notify
+        include T.def_steps(:validate, :save, :handle_errors, :notify)
+        #~meths end
+      end
+    end
+    #:pass end
+
+    it "what" do
+      assert_invoke Memo::Operation::Create, seq: "[:validate, :save, :notify]"
+      assert_invoke Memo::Operation::Create, validate: false, terminus: :failure, seq: "[:validate, :handle_errors]"
+    end
+  end
+end

data/test/operation_test.rb

@@ -1,5 +1,55 @@
 require "test_helper"
 
+# Tests around {Operation.call}.
+class OperationTest < Minitest::Spec
+  class Noop < Trailblazer::Operation
+    def self.capture_circuit_options((ctx, flow_options), **circuit_options)
+      ctx[:capture_circuit_options] = circuit_options.keys.inspect
+
+      return Trailblazer::Activity::Right, [ctx, flow_options]
+    end
+
+    step task: method(:capture_circuit_options)
+  end
+
+  # Mixing keywords and string keys in {Operation.call}.
+  # Test that {.(params: {}, "current_user" => user)} is processed properly
+
+  it "doesn't mistake circuit options as ctx variables when using circuit-interface" do
+    signal, (ctx, _) = Noop.call(
+      [{params: {}}, {}],
+      # real circuit_options
+      variable_for_circuit_options: true
+    ) # call_with_public_interface
+    #@ {:variable_for_circuit_options} is not supposed to be in {ctx}.
+    assert_equal CU.inspect(ctx), %({:params=>{}, :capture_circuit_options=>"[:variable_for_circuit_options, :exec_context, :activity, :runner]"})
+  end
+
+  it "doesn't mistake circuit options as ctx variables when using the call interface" do
+    result = Noop.call(
+      params:           {},
+      model:            true,
+      "current_user" => Object
+    ) # call with public interface.
+    #@ {:variable_for_circuit_options} is not supposed to be in {ctx}.
+    assert_result result, {params: {}, model: true, current_user: Object, capture_circuit_options: "[:wrap_runtime, :activity, :exec_context, :runner]"}
+  end
+
+#@ {#call_with_public_interface}
+  it "doesn't mistake circuit options as ctx variables when using circuit-interface" do
+    result = Noop.call_with_public_interface(
+      {params: {}},
+      {},
+      variable_for_circuit_options: true
+    ) # call_with_public_interface has two positional args, and kwargs for {circuit_options}.
+
+    assert_result result, {params: {}, capture_circuit_options: "[:variable_for_circuit_options, :wrap_runtime, :activity, :exec_context, :runner]"}
+    # assert_equal result.inspect, %(<Result:true #<Trailblazer::Context::Container wrapped_options={:params=>{}} mutable_options={:capture_circuit_options=>\"[:variable_for_circuit_options, :wrap_runtime, :activity, :exec_context, :runner]\"}> >)
+  end
+end
+
+# TODO: remove this test as many cases are covered via autogenerated activity tests.
+
 class DeclarativeApiTest < Minitest::Spec
   it "doesn't invoke {call} twice when using public interface" do
     class MyOp < Trailblazer::Operation
@@ -33,7 +83,7 @@ class DeclarativeApiTest < Minitest::Spec
     pass :wasnt_ok!
     pass :was_ok!
     fail :return_true!
-    fail :return_false!
+    left :return_false!
 
     step :bla, input: ->(ctx, *) { {id: ctx.inspect} }, output: ->(scope, ctx) { ctx["hello"] = scope["1"]; ctx }
 
@@ -117,17 +167,6 @@ class DeclarativeApiTest < Minitest::Spec
     Unset. ("params" => {decide: true}).inspect("a", "b", "c", "d", "e").must_equal %{<Result:true [false, true, nil, 1, 2] >}
   end
 
-# Mixing keywords and string keys in {Operation.call}.
-# Test that {.(params: {}, "current_user" => user)} is processed properly
-  class Collect < Trailblazer::Operation
-    # step ->(ctx, **) { ctx[:keys] }
-  end
-
-  it "contains all keys from {call}" do
-    result = Collect.(params: {}, "current_user" => Module)
-    _(result.inspect).must_equal %{<Result:true #<Trailblazer::Context::Container wrapped_options={:params=>{}, \"current_user\"=>Module} mutable_options={}> >}
-  end
-
   #---
   #- ctx container
   it do
@@ -141,9 +180,10 @@ class DeclarativeApiTest < Minitest::Spec
     signal, (ctx, _) = Update.([Update.options_for_public_call(options), {}], **{})
 
     signal.inspect.must_equal %{#<Trailblazer::Activity::Railway::End::Success semantic=:success>}
-    ctx.inspect.must_equal %{#<Trailblazer::Context::Container wrapped_options={\"params\"=>{:decide=>true}} mutable_options={\"a\"=>false, \"b\"=>true}>}
+    assert_equal ctx.inspect, %(#<Trailblazer::Context::Container wrapped_options=#{{"params" => {:decide=>true}}} mutable_options=#{{"a" => false, "b" => true}}>)
 
     # Call by passing aliases as an argument.
+    # This uses {#call}'s second positional argument.
     if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")
       result = Update.(
         options,

data/test/result_test.rb

@@ -19,7 +19,7 @@ class RailwayResultTest < Minitest::Spec
 
   #---
   # inspect
-  it { success.inspect.must_equal %{<Result:true {\"x\"=>String} >} }
+  it { assert_equal success.inspect, %(<Result:true #{{"x" => String}} >) }
   it { Result.new(true, {"x" => true, "y" => 1, "z" => 2}, event).inspect("z", "y").must_equal %{<Result:true [2, 1] >} }
 
   class Create < Trailblazer::Operation

data/test/test_helper.rb

@@ -1,15 +1,27 @@
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "trailblazer/operation"
+require "minitest/autorun"
 
 require "pp"
+require "trailblazer/operation"
 
-require "minitest/autorun"
 require "trailblazer/activity/testing"
 require "trailblazer/developer/render/linear"
+require "trailblazer/core"
 
 Minitest::Spec.class_eval do
-  Activity = Trailblazer::Activity
-  T = Activity::Testing
+  T = Trailblazer::Activity::Testing
+  include Trailblazer::Activity::Testing::Assertions
+  CU = Trailblazer::Core::Utils
+
+  def assert_equal(asserted, expected, *args)
+    super(expected, asserted, *args)
+  end
+
+  def assert_result(result, variables, outcome: true)
+    assert_equal result.success?, outcome
+
+    # assert_equal result.send(:data).sort_by { |key,  _| key.to_s }.to_h.inspect, variables.sort_by { |key, _| key.to_s }.to_h.inspect
+    assert_equal result.send(:data).to_h, variables
+  end
 end
 
 # TODO: replace all this with {Activity::Testing.def_steps}

data/test/trace_test.rb

@@ -12,15 +12,14 @@ class TraceTest < Minitest::Spec
     step ->(options, **) { options[:c] = true }, id: "Create.task.c"
     step ->(_options, params:, **) { params.any? }, id: "Create.task.params"
   end
-  # raise Create["__task_wraps__"].inspect
 
   it "allows using low-level Operation::Trace" do
-    result = Trailblazer::Operation::Trace.(
+    stack, result = Trailblazer::Developer::Trace.(
       Create,
       { a_return: true, params: {} },
     )
 
-    output = result.wtf
+    output = Trailblazer::Developer::Trace::Present.(stack)
 
     assert_equal output.gsub(/0x\w+/, "").gsub(/@.+_test/, ""), %{TraceTest::Create
 |-- Start.default
@@ -35,21 +34,6 @@ class TraceTest < Minitest::Spec
 `-- End.failure}
   end
 
-  it "Operation::trace" do
-    result = Create.trace(params: {x: 1}, a_return: true)
-    assert_equal result.wtf.gsub(/0x\w+/, "").gsub(/@.+_test/, ""), %{TraceTest::Create
-|-- Start.default
-|-- Create.task.a
-|-- MyNested
-|   |-- Start.default
-|   |-- B.task.b
-|   |-- B.task.e
-|   `-- End.success
-|-- Create.task.c
-|-- Create.task.params
-`-- End.success}
-  end
-
   it "Operation.wtf?" do
     result = nil
     output, = capture_io do
@@ -71,6 +55,6 @@ class TraceTest < Minitest::Spec
 
     result.success?.must_equal true
     result[:a_return].must_equal true
-    result[:params].inspect.must_equal %{{:x=>1}}
+    assert_equal CU.inspect(result[:params]), %({:x=>1})
   end
 end

data/trailblazer-operation.gemspec

@@ -17,13 +17,14 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "trailblazer-activity-dsl-linear",  ">= 1.2.0", "< 1.4.0"
-  spec.add_dependency "trailblazer-developer"
+  spec.add_dependency "trailblazer-activity-dsl-linear",  ">= 1.2.3", "< 1.4.0"
+  spec.add_dependency "trailblazer-developer", ">= 0.1.0", "< 0.2.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "minitest-line"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "trailblazer-core-utils"
 
   spec.required_ruby_version = ">= 2.5.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-operation
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Nick Sutterer
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-02 00:00:00.000000000 Z
+date: 2024-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trailblazer-activity-dsl-linear
@@ -16,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.2.3
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.4.0
@@ -26,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.2.3
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.4.0
@@ -36,14 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +105,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: trailblazer-core-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Trailblazer's operation object.
 email:
 - apotonick@gmail.com
@@ -119,16 +138,24 @@ files:
 - lib/trailblazer/operation/public_call.rb
 - lib/trailblazer/operation/railway.rb
 - lib/trailblazer/operation/result.rb
-- lib/trailblazer/operation/trace.rb
 - lib/trailblazer/operation/version.rb
+- lib/trailblazer/operation/wtf.rb
 - test/benchmark/skill_resolver_benchmark.rb
 - test/call_test.rb
-- test/callable_test.rb
 - test/class_dependencies_test.rb
+- test/docs/autogenerated/activity_basics_test.rb
+- test/docs/autogenerated/composable_variable_mapping_test.rb
+- test/docs/autogenerated/fast_track_layout_test.rb
+- test/docs/autogenerated/mechanics_test.rb
+- test/docs/autogenerated/sequence_options_test.rb
+- test/docs/autogenerated/subprocess_test.rb
+- test/docs/autogenerated/wiring_api_test.rb
 - test/docs/class_dependencies_test.rb
-- test/docs/doormat_test.rb
-- test/docs/macaroni_test.rb
+- test/docs/developer_test.rb
 - test/docs/operation_test.rb
+- test/docs/public_call_monkeypatching_test.rb
+- test/docs/result_test.rb
+- test/docs/step_dsl_test.rb
 - test/docs/wiring_test.rb
 - test/fast_track_test.rb
 - test/gemfiles/Gemfile.ruby-1.9
@@ -139,19 +166,14 @@ files:
 - test/introspect_test.rb
 - test/operation_test.rb
 - test/result_test.rb
-- test/skill_test.rb
 - test/step_test.rb
 - test/test_helper.rb
 - test/trace_test.rb
-- test/wire_test.rb
-- test/wiring/defaults_test.rb
-- test/wiring/subprocess_test.rb
 - trailblazer-operation.gemspec
 homepage: https://trailblazer.to/2.1/docs/operation.html
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -166,19 +188,26 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key: 
+rubygems_version: 3.6.0.dev
 specification_version: 4
 summary: Trailblazer's operation object with railway flow and integrated error handling.
 test_files:
 - test/benchmark/skill_resolver_benchmark.rb
 - test/call_test.rb
-- test/callable_test.rb
 - test/class_dependencies_test.rb
+- test/docs/autogenerated/activity_basics_test.rb
+- test/docs/autogenerated/composable_variable_mapping_test.rb
+- test/docs/autogenerated/fast_track_layout_test.rb
+- test/docs/autogenerated/mechanics_test.rb
+- test/docs/autogenerated/sequence_options_test.rb
+- test/docs/autogenerated/subprocess_test.rb
+- test/docs/autogenerated/wiring_api_test.rb
 - test/docs/class_dependencies_test.rb
-- test/docs/doormat_test.rb
-- test/docs/macaroni_test.rb
+- test/docs/developer_test.rb
 - test/docs/operation_test.rb
+- test/docs/public_call_monkeypatching_test.rb
+- test/docs/result_test.rb
+- test/docs/step_dsl_test.rb
 - test/docs/wiring_test.rb
 - test/fast_track_test.rb
 - test/gemfiles/Gemfile.ruby-1.9
@@ -189,10 +218,6 @@ test_files:
 - test/introspect_test.rb
 - test/operation_test.rb
 - test/result_test.rb
-- test/skill_test.rb
 - test/step_test.rb
 - test/test_helper.rb
 - test/trace_test.rb
-- test/wire_test.rb
-- test/wiring/defaults_test.rb
-- test/wiring/subprocess_test.rb

data/lib/trailblazer/operation/trace.rb

@@ -1,53 +0,0 @@
-require 'delegate'
-require "trailblazer/developer"
-
-module Trailblazer
-  class Operation
-    module Trace
-      # @note The problem in this method is, we have redundancy with Operation::PublicCall
-      def self.call(operation, options)
-        # warn %{Trailblazer: `Operation.trace` is deprecated. Please use `Operation.wtf?`.} # DISCUSS: should this be deprecated?
-        ctx = PublicCall.options_for_public_call(options) # redundant with PublicCall::call.
-
-        stack, signal, (ctx, _flow_options) = Developer::Trace.(operation, [ctx, {}])
-
-        result = Railway::Result(signal, ctx) # redundant with PublicCall::call.
-
-        Result.new(result, 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(options)
-        Trace.(self, options)
-      end
-
-      def wtf?(options)
-        call_with_public_interface(options, {}, invoke_class: Developer::Wtf)
-      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
-
-        # TODO: deprecate!
-        def wtf
-          Developer::Trace::Present.(@stack)
-        end
-
-        # TODO: deprecate!
-        def wtf?
-          puts wtf
-        end
-      end
-    end
-  end
-end