flow 0.3.0 → 0.9.0

data/lib/flow/operation/callbacks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Callbacks provide an extensible mechanism for hooking into a Operation.
+module Operation
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+      define_callbacks :failure, :execute, :behavior, :rewind, :undo
+    end
+
+    class_methods do
+      def on_failure(*filters, &block)
+        set_callback(:failure, :before, *filters, &block)
+      end
+    end
+  end
+end

data/lib/flow/operation/error_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# An unhandled error during execution is exceptional, and handlers unable to rescue an error cause a failure instead.
+module Operation
+  module ErrorHandler
+    extend ActiveSupport::Concern
+
+    class_methods do
+      private
+
+      def handle_error(error_class, problem: error_class.name.demodulize.underscore, with: nil, &block)
+        failure problem
+
+        rescue_from(error_class) { |exception| fail!(problem.to_sym, exception: exception) }
+
+        if with.present?
+          rescue_from(error_class, with: with)
+        elsif block_given?
+          rescue_from(error_class, &block)
+        end
+      end
+    end
+  end
+end

data/lib/flow/operation/execute.rb

@@ -1,27 +1,40 @@
 # frozen_string_literal: true
 
-# Execute the operation.
+# Operations *must* define the `#behavior` that occurs when `#execute` is called.
 module Operation
   module Execute
     extend ActiveSupport::Concern
 
-    class_methods do
-      def execute(*arguments)
-        new(*arguments).execute
+    included do
+      include ActiveSupport::Rescuable
+
+      attr_reader :operation_failure
+
+      set_callback :execute, :around, ->(_, block) { surveil(:execute) { block.call } }
+    end
+
+    def execute!
+      run_callbacks(:execute) do
+        run_callbacks(:behavior) { behavior }
       end
+
+      self
+    rescue StandardError => exception
+      rescue_with_handler(exception) || raise
+
+      self
     end
 
     def execute
-      raise NotImplementedError
-    end
+      execute!
+    rescue Operation::Failures::OperationFailure => exception
+      @operation_failure = exception
 
-    included do
-      include AroundTheWorld
-      include Technologic
+      self
+    end
 
-      around_method :execute, prevent_double_wrapping_for: Technologic do
-        surveil(:execute) { super() }
-      end
+    def behavior
+      # abstract method which should be defined by descendants with the functionality of the given operation
     end
   end
 end

data/lib/flow/operation/failures.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# When `#execute` is unsuccessful, expected problems are *failures* and unexpected problems are *Exceptions*.
+module Operation
+  module Failures
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_failures, instance_writer: false, default: []
+
+      delegate :_failures, to: :class
+    end
+
+    class_methods do
+      def inherited(base)
+        base._failures = _failures.dup
+        super
+      end
+
+      private
+
+      def failure(problem)
+        problem = problem.to_s.to_sym
+        warn(:problem_already_defined) if _failures.include? problem
+
+        _failures << problem
+        define_callbacks problem
+        define_on_failure_for_problem(problem)
+        define_fail_method_for_problem(problem)
+      end
+
+      def define_on_failure_for_problem(problem)
+        on_failure_name = "on_#{problem}_failure".to_sym
+        return if respond_to?(on_failure_name)
+
+        define_singleton_method(on_failure_name) { |*filters, &block| set_callback(problem, :before, *filters, &block) }
+      end
+
+      def define_fail_method_for_problem(problem)
+        problem_failure_name = "#{problem}_failure!".to_sym
+        return if method_defined?(problem_failure_name)
+
+        define_method(problem_failure_name) { |**details| fail!(problem, **details) }
+      end
+    end
+
+    def fail!(problem, **details)
+      run_callbacks(problem) do
+        run_callbacks(:failure) do
+          error! OperationFailure.new(problem, **details), **details
+        end
+      end
+    end
+
+    class OperationFailure < StandardError
+      attr_reader :problem, :details
+
+      def initialize(problem = nil, **details)
+        super(problem)
+        @problem = problem
+        @details = OpenStruct.new(details)
+      end
+    end
+  end
+end

data/lib/flow/operation/rewind.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# When something goes wrong in Flow, `#rewind` is called on all executed Operations to `#undo` their behavior.
+module Operation
+  module Rewind
+    extend ActiveSupport::Concern
+
+    included do
+      set_callback :rewind, :around, ->(_, block) { surveil(:rewind) { block.call } }
+    end
+
+    def rewind
+      run_callbacks(:rewind) do
+        run_callbacks(:undo) { undo }
+      end
+
+      self
+    end
+
+    def undo
+      # abstract method which should be defined by descendants to undo the functionality of the `#behavior` method
+    end
+  end
+end

data/lib/flow/operation/status.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# The Operation status is used by the Flow calling it to determine what to do next; continue on or stop and rollback.
+module Operation
+  module Status
+    extend ActiveSupport::Concern
+
+    included do
+      set_callback(:execute, :before) { self.was_executed = true }
+
+      private
+
+      attr_accessor :was_executed
+    end
+
+    def executed?
+      was_executed.present?
+    end
+
+    def failed?
+      operation_failure.present?
+    end
+
+    def success?
+      executed? && !failed?
+    end
+  end
+end

data/lib/flow/operation/transactions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# It's best practice to have Operations which modify several persisted objects to use a transaction.
+module Operation
+  module Transactions
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def callbacks_for_transaction
+        %i[behavior undo].freeze
+      end
+    end
+  end
+end

data/lib/flow/operation_base.rb

@@ -1,10 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "flow/errors/state_invalid"
+
+require_relative "operation/callbacks"
 require_relative "operation/core"
+require_relative "operation/error_handler"
 require_relative "operation/execute"
+require_relative "operation/failures"
+require_relative "operation/rewind"
+require_relative "operation/status"
+require_relative "operation/transactions"
 
 # Operations are service objects which are executed with a state.
 class OperationBase
+  include ShortCircuIt
+  include Technologic
+  include TransactionWrapper
+  include Operation::Callbacks
   include Operation::Core
+  include Operation::ErrorHandler
   include Operation::Execute
+  include Operation::Failures
+  include Operation::Rewind
+  include Operation::Status
+  include Operation::Transactions
 end

data/lib/flow/shoulda_matcher_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+if defined?(Shoulda::Matchers::ActiveModel)
+  RSpec.configure do |config|
+    config.include(Shoulda::Matchers::ActiveModel, type: :state)
+  end
+end

data/lib/flow/spec_helper.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "custom_matchers"
+require_relative "shoulda_matcher_helper"

data/lib/flow/state/arguments.rb

@@ -19,7 +19,7 @@ module State
         super
       end
 
-      protected
+      private
 
       def argument(argument)
         _arguments << argument

data/lib/flow/state/attributes.rb

@@ -17,14 +17,13 @@ module State
         super
       end
 
-      protected
+      private
 
       def define_attribute(attribute)
         _attributes << attribute
 
         attr_accessor attribute
         define_attribute_methods attribute
-        protected "#{attribute}=".to_sym
       end
     end
   end

data/lib/flow/state/callbacks.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# State callbacks provide an extensible mechanism for composing functionality for a state object.
+# Callbacks provide an extensible mechanism for hooking into a State.
 module State
   module Callbacks
     extend ActiveSupport::Concern

data/lib/flow/state/core.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Accepts input representing the arguments and input which define the initial state.
+# Accepts input representing the arguments and options which define the initial state.
 module State
   module Core
     extend ActiveSupport::Concern

data/lib/flow/state/options.rb

@@ -9,7 +9,9 @@ module State
       class_attribute :_options, instance_writer: false, default: {}
 
       set_callback :initialize, :after do
-        _options.each { |option, info| __send__("#{option}=".to_sym, info.default_value) if public_send(option).nil? }
+        _options.each do |option, info|
+          __send__("#{option}=".to_sym, info.default_value.dup) if public_send(option).nil?
+        end
       end
     end
 
@@ -20,7 +22,7 @@ module State
         super
       end
 
-      protected
+      private
 
       def option(option, default: nil, &block)
         _options[option] = Option.new(default: default, &block)

data/lib/flow/state/string.rb

@@ -5,8 +5,6 @@ module State
   module String
     extend ActiveSupport::Concern
 
-    delegate :name, to: :class, prefix: true
-
     def to_s
       string_for(__method__)
     end
@@ -15,16 +13,14 @@ module State
       string_for(__method__)
     end
 
-    protected
+    private
 
     def stringable_attributes
       self.class._attributes
     end
 
-    private
-
     def string_for(method)
-      "#<#{class_name} #{attribute_string(method)}>"
+      "#<#{self.class.name} #{attribute_string(method)}>"
     end
 
     def attribute_string(method)

data/lib/flow/state_base.rb

@@ -9,6 +9,8 @@ require_relative "state/string"
 
 # A flow state is the immutable structure of relevant data.
 class StateBase
+  include ShortCircuIt
+  include Technologic
   include ActiveModel::Model
   include State::Callbacks
   include State::Attributes

data/lib/flow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flow
-  VERSION = "0.3.0"
+  VERSION = "0.9.0"
 end

data/lib/generators/flow/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Stub an Flow and State with test.
+
+Example:
+    `rails generate flow foo`
+
+    Generates:
+       Flow: app/flows/foo_flow.rb
+      State: app/states/foo_state.rb
+       Test: spec/flows/foo_flow_spec.rb
+       Test: spec/states/foo_state_spec.rb

data/lib/generators/flow/application_flow/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Create the ApplicationFlow and test.
+
+Example:
+    `rails generate flow:application_flow`
+
+    Generates:
+       Flow: app/flows/application_flow.rb
+       Test: spec/flows/application_flow_spec.rb

data/lib/generators/flow/application_flow/application_flow_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Flow
+  module Generators
+    class ApplicationFlowGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      hook_for :test_framework
+
+      def create_application_flow
+        template "application_flow.rb", File.join("app/flows/application_flow.rb")
+      end
+    end
+  end
+end

data/lib/generators/flow/application_flow/templates/application_flow.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class ApplicationFlow < FlowBase; end

data/lib/generators/flow/application_operation/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Create the ApplicationOperation and test.
+
+Example:
+    `rails generate flow:application_operation`
+
+    Generates:
+  Operation: app/operations/application_operation.rb
+       Test: spec/operations/application_operation_spec.rb