flow 0.9.3 → 0.10.0

data/lib/flow.rb

@@ -4,6 +4,8 @@ require "active_model"
 require "active_record"
 require "active_support"
 
+require "instructor"
+require "short_circu_it"
 require "technologic"
 
 require "flow/version"

data/lib/flow/concerns/transaction_wrapper.rb

@@ -1,26 +1,19 @@
 # frozen_string_literal: true
 
 # A callback driven approach to wrap business logic within database transaction.
-module TransactionWrapper
-  extend ActiveSupport::Concern
+module Flow
+  module TransactionWrapper
+    extend ActiveSupport::Concern
 
-  class_methods do
-    def transaction_provider
-      ActiveRecord::Base
-    end
-
-    private
-
-    def wrap_in_transaction(only: nil, except: nil)
-      whitelist = Array.wrap(only).map(&:to_sym)
-      blacklist = Array.wrap(except).map(&:to_sym)
+    class_methods do
+      def transaction_provider
+        ActiveRecord::Base
+      end
 
-      callbacks_to_wrap = callbacks_for_transaction
-      callbacks_to_wrap &= whitelist if whitelist.present?
-      callbacks_to_wrap -= blacklist if blacklist.present?
+      private
 
-      callbacks_to_wrap.each do |method_name|
-        set_callback method_name, :around, ->(_, block) { self.class.transaction_provider.transaction { block.call } }
+      def wrap_in_transaction
+        set_callback callback_name, :around, ->(_, block) { self.class.transaction_provider.transaction { block.call } }
       end
     end
   end

data/lib/flow/custom_matchers.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "custom_matchers/define_argument"
-require_relative "custom_matchers/define_attribute"
-require_relative "custom_matchers/define_option"
+require_relative "custom_matchers/define_failure"
+require_relative "custom_matchers/define_output"
+require_relative "custom_matchers/handle_error"
 require_relative "custom_matchers/use_operations"
+require_relative "custom_matchers/wrap_in_transaction"
+require_relative "custom_matchers/have_on_state"

data/lib/flow/custom_matchers/define_failure.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `ApplicationOperation.failure`
+#
+#     class ExampleOperation
+#       failure :foo
+#     end
+#
+#     RSpec.describe ExampleOperation, type: :operation do
+#       subject { described_class.new(**input) }
+#
+#       let(:input) { {} }
+#
+#       it { is_expected.to define_failure :foo }
+#     end
+
+RSpec::Matchers.define :define_failure do |problem|
+  match { |operation| expect(operation._failures).to include problem.to_sym }
+  description { "defines failure #{problem}" }
+  failure_message { |operation| "expected #{operation.class.name} to define failure #{problem}" }
+end

data/lib/flow/custom_matchers/define_output.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `ApplicationState.output`
+#
+#     class ExampleState
+#       output :foo
+#       output :bar, default: :baz
+#       output(:gaz) { :haz }
+#     end
+#
+#     RSpec.describe ExampleState, type: :state do
+#       subject { described_class.new(**input) }
+#
+#       let(:input) { {} }
+#
+#       it { is_expected.to define_output :foo }
+#       it { is_expected.to define_output :bar, default: :baz }
+#       it { is_expected.to define_output :gaz, default: :haz }
+#     end
+
+RSpec::Matchers.define :define_output do |output, default: nil|
+  match do |state|
+    expect(state._defaults[output]&.value).to eq default
+    expect(state._outputs).to include output
+  end
+  description { "define output" }
+  failure_message { "expected #{described_class} to define output #{output} #{for_default(default)}" }
+
+  def for_default(default)
+    return "without a default value" if default.nil?
+
+    "with default value #{default}"
+  end
+end

data/lib/flow/custom_matchers/handle_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `ApplicationOperation.handle_error`
+#
+#     class ExampleFlow
+#       operations OperationOne, OperationTwo
+#     end
+#
+#     RSpec.describe ExampleFlow, type: :flow do
+#       subject { described_class.new(**input) }
+#
+#       let(:input) { {} }
+#
+#       it { is_expected.to use_operations OperationOne, OperationTwo }
+#     end
+
+RSpec::Matchers.define :handle_error do |error_class, problem: error_class.name.demodulize.underscore, with: nil|
+  match do |operation|
+    handlers = operation.rescue_handlers.select { |handler| handler[0] == error_class.to_s }
+
+    expect(handlers).to be_present
+
+    if with.present?
+      expect(handlers.find { |handler| (with == :a_block) ? handler[1].is_a?(Proc) : handler[1] == with }).to be_present
+    end
+
+    expect(operation).to define_failure problem
+  end
+
+  description { "handles error #{error_class}" }
+  failure_message { |flow| "expected #{flow.class.name} to handle error #{error_class}" }
+end

data/lib/flow/custom_matchers/have_on_state.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# RSpec matcher for making assertions on the state of a Flow or Operation after it has been run.
+#
+# class ExampleOperation
+#   def behavior
+#     state.foo = "some data"
+#     state.bar = "some other data"
+#   end
+# end
+#
+# class ExampleFlow
+#   operations [ ExampleOperation ]
+# end
+#
+# RSpec.describe ExampleOperation, type: :operation do
+#   subject { operation.execute }
+#
+#   it { is_expected.to have_on_state foo: "some data" }
+#   it { is_expected.to have_on_state foo: instance_of(String) }
+#   it { is_expected.to have_on_state foo: "some data", bar: "some other data" }
+# end
+#
+# RSpec.describe ExampleFlow, type: :operation do
+#   subject { flow.trigger }
+#
+#   it { is_expected.to have_on_state foo: "some data" }
+#   it { is_expected.to have_on_state foo: instance_of(String) }
+#   it { is_expected.to have_on_state foo: "some data", bar: "some other data" }
+# end
+
+module CustomMatchers
+  def have_on_state(expectations)
+    HaveOnState.new(expectations)
+  end
+
+  class HaveOnState
+    include RSpec::Matchers
+
+    def initialize(state_expectations)
+      @state_expectations = state_expectations
+    end
+
+    def matches?(object)
+      @state_expectations.all? do |key, value|
+        expect(object.state.public_send(key)).to match value
+      end
+    end
+
+    def description
+      "have the expected data on state"
+    end
+  end
+end

data/lib/flow/custom_matchers/use_operations.rb

@@ -1,23 +1,25 @@
 # frozen_string_literal: true
 
-# RSpec matcher for flow operations.
+# RSpec matcher that tests usage of `ApplicationFlow.operations`
 #
-# Usage:
+#     class ExampleFlow
+#       operations OperationOne, OperationTwo
+#     end
 #
-# RSpec.describe ExampleFlow, type: :flow do
-#   subject { described_class.new(**input) }
+#     RSpec.describe ExampleFlow, type: :flow do
+#       subject { described_class.new(**input) }
 #
-#   let(:input) { {} }
+#       let(:input) { {} }
 #
-#   it { is_expected.to use_operations [ OperationOne, OperationTwo ] }
-# end
+#       it { is_expected.to use_operations OperationOne, OperationTwo }
+#     end
 
-RSpec::Matchers.define :use_operations do |operations|
-  match { |flow| expect(flow._operations).to eq Array.wrap(operations) }
+RSpec::Matchers.define :use_operations do |*operations|
+  match { |flow| expect(flow._operations).to eq operations.flatten }
   description { "uses operations #{display_operations(operations)}" }
-  failure_message { |flow| "expected #{flow.class.name}# to use operations #{display_operations(operations)}" }
+  failure_message { |flow| "expected #{flow.class.name} to use operations #{display_operations(operations)}" }
 
   def display_operations(operations)
-    Array.wrap(operations).join(", ")
+    operations.flatten.join(", ")
   end
 end

data/lib/flow/custom_matchers/wrap_in_transaction.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.wrap_in_transaction` for `ApplicationFlow` or `ApplicationOperation`
+#
+#     class ExampleFlow
+#       wrap_in_transaction
+#       operations OperationOne, OperationTwo
+#     end
+#
+#     class ExampleState
+#       wrap_in_transaction
+#     end
+#
+#     RSpec.describe ExampleFlow, type: :flow do
+#       subject { described_class.new(**input) }
+#
+#       let(:input) { {} }
+#
+#       it { is_expected.to wrap_in_transaction }
+#     end
+#
+#     RSpec.describe Example, type: :operation do
+#       subject(:operation) { described_class.new(state) }
+#
+#       let(:state) { example_state_class.new(**state_input) }
+#       let(:example_state_class) { Class.new(ApplicationState) }
+#       let(:state_input) do
+#         {}
+#       end
+#
+#       it { is_expected.to wrap_in_transaction }
+#     end
+
+# rubocop:disable Metrics/BlockLength
+RSpec::Matchers.define :wrap_in_transaction do
+  match do |instance|
+    callback_name = instance.class.callback_name
+    original_transaction_count = instance.class.transaction_provider.connection.open_transactions
+
+    allow(instance).to receive(callback_name) do
+      expect(instance.class.transaction_provider.connection.open_transactions).to eq original_transaction_count + 1
+    end
+
+    instance.run_callbacks(callback_name) { instance.public_send(callback_name) }
+    expect(instance).to have_received(callback_name)
+  end
+
+  description do
+    "wrap in a transaction"
+  end
+
+  failure_message do |instance|
+    "expected #{instance.class.name} to wrap in a transaction"
+  end
+
+  def pretty_callbacks(callbacks)
+    callbacks.join(", ")
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/flow/flow/callbacks.rb

@@ -7,7 +7,7 @@ module Flow
 
     included do
       include ActiveSupport::Callbacks
-      define_callbacks :initialize, :trigger, :flux, :revert, :ebb
+      define_callbacks :initialize, :trigger, :flux
     end
   end
 end

data/lib/flow/flow/core.rb

@@ -13,6 +13,7 @@ module Flow
 
     included do
       delegate :state_class, to: :class
+      delegate :outputs, to: :state
 
       attr_reader :state
     end

data/lib/flow/flow/flux.rb

@@ -41,8 +41,6 @@ module Flow
     rescue StandardError => exception
       error :error_executing_operation, state: state, exception: exception
 
-      revert
-
       raise exception unless exception.is_a? Flow::Flux::Failure
     end
 

data/lib/flow/flow/status.rb

@@ -20,9 +20,5 @@ module Flow
     def failed?
       triggered? && !success?
     end
-
-    def reverted?
-      rewound_operations.any?
-    end
   end
 end

data/lib/flow/flow/transactions.rb

@@ -6,8 +6,8 @@ module Flow
     extend ActiveSupport::Concern
 
     class_methods do
-      def callbacks_for_transaction
-        %i[flux ebb].freeze
+      def callback_name
+        :flux
       end
     end
   end

data/lib/flow/flow/trigger.rb

@@ -16,7 +16,7 @@ module Flow
     end
 
     included do
-      delegate :valid?, to: :state, prefix: true
+      delegate :valid?, :validated?, to: :state, prefix: true
 
       set_callback :trigger, :around, ->(_, block) { surveil(:trigger) { block.call } }
     end

data/lib/flow/flow_base.rb

@@ -4,26 +4,24 @@ require_relative "flow/errors/state_invalid"
 
 require_relative "flow/callbacks"
 require_relative "flow/core"
-require_relative "flow/ebb"
 require_relative "flow/flux"
 require_relative "flow/operations"
-require_relative "flow/revert"
 require_relative "flow/status"
 require_relative "flow/transactions"
 require_relative "flow/trigger"
 
 # A **Flow** is a collection of procedurally executed **Operations** sharing a common **State**.
-class FlowBase
-  include ShortCircuIt
-  include Technologic
-  include TransactionWrapper
-  include Flow::Callbacks
-  include Flow::Core
-  include Flow::Ebb
-  include Flow::Flux
-  include Flow::Operations
-  include Flow::Revert
-  include Flow::Status
-  include Flow::Transactions
-  include Flow::Trigger
+module Flow
+  class FlowBase
+    include ShortCircuIt
+    include Technologic
+    include Flow::TransactionWrapper
+    include Flow::Callbacks
+    include Flow::Core
+    include Flow::Flux
+    include Flow::Operations
+    include Flow::Status
+    include Flow::Transactions
+    include Flow::Trigger
+  end
 end

data/lib/flow/operation/accessors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Flow
+  module Operation
+    module Accessors
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_state_readers, instance_writer: false, default: []
+        class_attribute :_state_writers, instance_writer: false, default: []
+        class_attribute :_state_accessors, instance_writer: false, default: []
+      end
+
+      class_methods do
+        protected
+
+        def state_reader(name)
+          return unless _add_state_reader_tracker(name.to_sym)
+
+          delegate name, to: :state
+        end
+
+        def state_writer(name)
+          return unless _add_state_writer_tracker(name.to_sym)
+
+          delegate("#{name}=", to: :state)
+        end
+
+        def state_accessor(name)
+          state_reader name
+          state_writer name
+        end
+
+        private
+
+        def _add_state_reader_tracker(name)
+          return false if _state_readers.include?(name)
+
+          _add_state_accessor_tracker(name) if _state_writers.include?(name)
+          _state_readers << name
+        end
+
+        def _add_state_writer_tracker(name)
+          return false if _state_writers.include?(name)
+
+          _add_state_accessor_tracker(name) if _state_readers.include?(name)
+          _state_writers << name
+        end
+
+        def _add_state_accessor_tracker(name)
+          return if _state_accessors.include?(name)
+
+          _state_accessors << name
+        end
+
+        def inherited(base)
+          base._state_readers = _state_readers.dup
+          base._state_writers = _state_writers.dup
+          base._state_accessors = _state_accessors.dup
+
+          super
+        end
+      end
+    end
+  end
+end