flow 0.3.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a25492b68978e0c6dd95fe793c915181ec5943da1009c95e3411529aed8947
-  data.tar.gz: a652814c8cf408281de94acf9197d040ba458cc07e547592bd485a35097cbc67
+  metadata.gz: 06cd9cd8135b5b9c52b88e812c87250ada48cb408a2bff65d32b72440c89994d
+  data.tar.gz: f876e5506c3753696e4ea2f11c4f8f9f903648d290040d8099a7ebfac68ff0e2
 SHA512:
-  metadata.gz: 047c0d4f98028c99f8929fb8d850b6b35772a1689d28e268caa0944486b1ca8960bebc8335f36bd21a45f68a201076e9640d3558feb6f9c7efedcdef9a44dbe0
-  data.tar.gz: 983411cc472456dad56653736ec4e8430919fdc0af6fb15f6076b2d684e10279695017061766aa7d8495245ba501ffd4ee93c74ad3b385ac64d4b9cddab7758d
+  metadata.gz: 92dc6d0367748c85ddff07a3d9b0c2ed0eb76090a1fa5707f1d2305ea876e2184e279b5278d6d94c8a812e4f045e06c0a46c2945278789f9d346b95c5984f4c2
+  data.tar.gz: 377228fbebeac2e36d6ff0ce56f6f7b50383f62ae434f75e661803e71663e90ef246d328985fb481dd827818ed9fc67483a9a7fa860459bed9839c834fc07eea

data/lib/flow.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 require "active_model"
-
+require "active_record"
 require "active_support"
-require "active_support/core_ext/class/attribute"
-require "active_support/core_ext/module/delegation"
 
 require "technologic"
 
 require "flow/version"
 
+require "flow/concerns/transaction_wrapper"
+
 require "flow/flow_base"
 require "flow/operation_base"
 require "flow/state_base"

data/lib/flow/concerns/transaction_wrapper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# A callback driven approach to wrap some business logic within a transaction.
+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)
+
+      callbacks_to_wrap = callbacks_for_transaction
+      callbacks_to_wrap &= whitelist if whitelist.present?
+      callbacks_to_wrap -= blacklist if blacklist.present?
+
+      callbacks_to_wrap.each do |method_name|
+        set_callback method_name, :around, ->(_, block) { self.class.transaction_provider.transaction { block.call } }
+      end
+    end
+  end
+end

data/lib/flow/custom_matchers.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "custom_matchers/define_argument"
+require_relative "custom_matchers/define_option"
+require_relative "custom_matchers/use_operations"

data/lib/flow/custom_matchers/define_argument.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# RSpec matcher for flow state arguments.
+#
+# Usage:
+#
+# RSpec.describe ExampleState, type: :state do
+#   subject { described_class.new(**input) }
+#
+#   let(:input) { {} }
+#
+#   it { is_expected.to define_argument :foo }
+# end
+
+RSpec::Matchers.define :define_argument do |argument|
+  match { |state| expect(state._arguments).to include argument }
+  description { "has argument #{argument}" }
+  failure_message { |state| "expected #{state.class.name}# to have argument #{argument}" }
+end

data/lib/flow/custom_matchers/define_option.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# RSpec matcher for flow state options.
+#
+# Usage:
+#
+# RSpec.describe ExampleState, type: :state do
+#   subject { described_class.new(**input) }
+#
+#   let(:input) { {} }
+#
+#   it { is_expected.to define_option :foo }
+#   it { is_expected.to define_option :foo, default_value }
+# end
+
+RSpec::Matchers.define :define_option do |option, default_value = nil|
+  match { |state| expect(state._options[option].default_value).to eq default_value }
+  description { "has option #{option}" }
+  failure_message { |state| "expected #{state.class.name}# to have option #{option}, #{for_default(default_value)}" }
+
+  def for_default(default_value)
+    return "without a default value" if default_value.nil?
+
+    "with default value #{default_value}"
+  end
+end

data/lib/flow/custom_matchers/use_operations.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# RSpec matcher for flow operations.
+#
+# Usage:
+#
+# 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 :use_operations do |operations|
+  match { |flow| expect(flow._operations).to eq Array.wrap(operations) }
+  description { "uses 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(", ")
+  end
+end

data/lib/flow/flow/callbacks.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Callbacks provide an extensible mechanism for hooking into a Flow.
+module Flow
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+      define_callbacks :initialize, :trigger, :flux, :revert, :ebb
+    end
+  end
+end

data/lib/flow/flow/core.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Accepts input representing the arguments and options which define the initial state.
+module Flow
+  module Core
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def state_class
+        "#{name.chomp("Flow")}State".constantize
+      end
+    end
+
+    included do
+      delegate :state_class, to: :class
+
+      attr_reader :state
+    end
+
+    def initialize(**input)
+      run_callbacks(:initialize) { @state = state_class.new(**input) }
+    end
+  end
+end

data/lib/flow/flow/ebb.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# When a `#revert` is called on a Flow, `#rewind` is called on Operations in reverse of the order they were executed.
+module Flow
+  module Ebb
+    extend ActiveSupport::Concern
+
+    included do
+      set_callback(:initialize, :after) { @rewound_operations = [] }
+
+      private
+
+      attr_reader :rewound_operations
+
+      def _ebb
+        rewindable_operations.reverse_each { |executed_operation| rewound_operations << executed_operation.rewind }
+      end
+
+      def rewindable_operations
+        executed_operations - rewound_operations
+      end
+    end
+
+    def ebb
+      run_callbacks(:ebb) { _ebb }
+    end
+  end
+end

data/lib/flow/flow/errors/state_invalid.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Flow
+  module Errors
+    class StateInvalid < StandardError; end
+  end
+end

data/lib/flow/flow/flux.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# When `#trigger` is called on a Flow, `#execute` is called on Operations sequentially in their given order.
+module Flow
+  module Flux
+    extend ActiveSupport::Concern
+
+    included do
+      set_callback(:initialize, :after) { @executed_operations = [] }
+
+      attr_reader :failed_operation
+
+      private
+
+      attr_reader :executed_operations
+
+      def _flux
+        executable_operations.each do |operation|
+          operation.execute
+          (@failed_operation = operation) and raise Flow::Flux::Failure if operation.failed?
+          executed_operations << operation
+        end
+      end
+
+      def executable_operations
+        operation_instances - executed_operations
+      end
+
+      def operation_instances
+        _operations.map { |operation_class| operation_class.new(state) }
+      end
+      memoize :operation_instances
+    end
+
+    def failed_operation?
+      failed_operation.present?
+    end
+
+    def flux
+      flux!
+    rescue StandardError => exception
+      error :error_executing_operation, state: state, exception: exception
+
+      revert
+
+      raise exception unless exception.is_a? Flow::Flux::Failure
+    end
+
+    def flux!
+      run_callbacks(:flux) { _flux }
+    end
+
+    class Failure < StandardError; end
+  end
+end

data/lib/flow/flow/operations.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Operations are an ordered list of the behaviors which should are executed with and possibly change the Flow's state.
+module Flow
+  module Operations
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_operations, instance_writer: false, default: []
+
+      delegate :_operations, to: :class
+    end
+
+    class_methods do
+      def inherited(base)
+        base._operations = _operations.dup
+        super
+      end
+
+      private
+
+      def operations(*operations)
+        _operations.concat(operations.flatten)
+      end
+    end
+  end
+end

data/lib/flow/flow/revert.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Reverting a Flow rewinds all its executed operations in reverse order (see `Flow::Ebb`).
+module Flow
+  module Revert
+    extend ActiveSupport::Concern
+
+    included do
+      set_callback :revert, :around, ->(_, block) { surveil(:revert) { block.call } }
+    end
+
+    def revert
+      run_callbacks(:revert) { ebb }
+
+      state
+    end
+  end
+end

data/lib/flow/flow/status.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# The Flow status is a summary of what has occurred during the runtime, used mainly for analysis and program flow.
+module Flow
+  module Status
+    extend ActiveSupport::Concern
+
+    def pending?
+      executed_operations.none?
+    end
+
+    def triggered?
+      executed_operations.any?
+    end
+
+    def success?
+      triggered? && (operation_instances - executed_operations).none?
+    end
+
+    def failed?
+      triggered? && !success?
+    end
+
+    def reverted?
+      rewound_operations.any?
+    end
+  end
+end

data/lib/flow/flow/transactions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# It's best practice to have Flows in which nothing should be done unless everything is successful to use a transaction.
+module Flow
+  module Transactions
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def callbacks_for_transaction
+        %i[flux ebb].freeze
+      end
+    end
+  end
+end

data/lib/flow/flow/trigger.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Triggering a Flow executes all its operations in sequential order (see `Flow::Flux`) *iff* it has a valid state.
+module Flow
+  module Trigger
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def trigger!(*arguments)
+        new(*arguments).trigger!
+      end
+
+      def trigger(*arguments)
+        new(*arguments).trigger
+      end
+    end
+
+    included do
+      delegate :valid?, to: :state, prefix: true
+
+      set_callback :trigger, :around, ->(_, block) { surveil(:trigger) { block.call } }
+    end
+
+    def trigger!
+      raise Flow::Errors::StateInvalid unless state_valid?
+
+      run_callbacks(:trigger) { flux }
+
+      self
+    end
+
+    def trigger
+      trigger!
+    rescue Flow::Errors::StateInvalid
+      self
+    end
+  end
+end

data/lib/flow/flow_base.rb

@@ -1,43 +1,29 @@
 # frozen_string_literal: true
 
+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
-
-  class_attribute :_operations, instance_writer: false, default: []
-
-  class << self
-    def state_class
-      "#{name.chomp("Flow")}State".constantize
-    end
-
-    def trigger(*arguments)
-      new(*arguments).trigger
-    end
-
-    def operations(*operations)
-      _operations.concat(operations.flatten)
-    end
-
-    def inherited(base)
-      base._operations = _operations.dup
-      super
-    end
-  end
-
-  attr_reader :state
-
-  delegate :state_class, :_operations, to: :class
-
-  def initialize(**input)
-    @state = state_class.new(**input)
-  end
-
-  def trigger
-    surveil(:trigger) do
-      _operations.each { |operation| operation.execute(state) }
-    end
-
-    state
-  end
+  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
 end