flow 0.9.2 → 0.9.3

data/lib/flow/concerns/transaction_wrapper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# A callback driven approach to wrap some business logic within a transaction.
+# A callback driven approach to wrap business logic within database transaction.
 module TransactionWrapper
   extend ActiveSupport::Concern
 

data/lib/flow/custom_matchers.rb

@@ -1,5 +1,6 @@
 # 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/use_operations"

data/lib/flow/custom_matchers/define_attribute.rb

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

data/lib/flow/flow/operations.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Operations are an ordered list of the behaviors which should are executed with and possibly change the Flow's state.
+# Operations are an ordered list of the behaviors which are executed with (and possibly change) the Flow's state.
 module Flow
   module Operations
     extend ActiveSupport::Concern

data/lib/flow/flow/status.rb

@@ -10,7 +10,7 @@ module Flow
     end
 
     def triggered?
-      executed_operations.any?
+      executed_operations.any? || failed_operation?
     end
 
     def success?

data/lib/flow/flow/transactions.rb

@@ -1,6 +1,6 @@
 # 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.
+# Flows where no operation should be persisted unless all are successful should use a transaction.
 module Flow
   module Transactions
     extend ActiveSupport::Concern

data/lib/flow/flow_base.rb

@@ -12,7 +12,7 @@ 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.
+# A **Flow** is a collection of procedurally executed **Operations** sharing a common **State**.
 class FlowBase
   include ShortCircuIt
   include Technologic

data/lib/flow/operation/core.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Accepts input representing the state.
+# Operations take a state as input.
 module Operation
   module Core
     extend ActiveSupport::Concern

data/lib/flow/operation/error_handler.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# An unhandled error during execution is exceptional, and handlers unable to rescue an error cause a failure instead.
+# When an exception is raised during during execution, but a handler can rescue, it causes a failure instead.
 module Operation
   module ErrorHandler
     extend ActiveSupport::Concern

data/lib/flow/operation/errors/already_executed.rb

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

data/lib/flow/operation/errors/already_rewound.rb

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

data/lib/flow/operation/execute.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Operations *must* define the `#behavior` that occurs when `#execute` is called.
+# Operations define a `#behavior` that occurs when `#execute` is called.
 module Operation
   module Execute
     extend ActiveSupport::Concern
@@ -11,6 +11,7 @@ module Operation
       attr_reader :operation_failure
 
       set_callback :execute, :around, ->(_, block) { surveil(:execute) { block.call } }
+      set_callback :execute, :before, -> { raise Operation::Errors::AlreadyExecuted }, if: :executed?
     end
 
     def execute!

data/lib/flow/operation/failures.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# When `#execute` is unsuccessful, expected problems are *failures* and unexpected problems are *Exceptions*.
+# When `#execute` is unsuccessful, expected problems are **failures** and unexpected problems are **Exceptions**.
 module Operation
   module Failures
     extend ActiveSupport::Concern

data/lib/flow/operation/rewind.rb

@@ -7,6 +7,7 @@ module Operation
 
     included do
       set_callback :rewind, :around, ->(_, block) { surveil(:rewind) { block.call } }
+      set_callback :rewind, :before, -> { raise Operation::Errors::AlreadyRewound }, if: :rewound?
     end
 
     def rewind

data/lib/flow/operation/status.rb

@@ -7,16 +7,21 @@ module Operation
 
     included do
       set_callback(:execute, :before) { self.was_executed = true }
+      set_callback(:rewind, :before) { self.was_rewound = true }
 
       private
 
-      attr_accessor :was_executed
+      attr_accessor :was_executed, :was_rewound
     end
 
     def executed?
       was_executed.present?
     end
 
+    def rewound?
+      was_rewound.present?
+    end
+
     def failed?
       operation_failure.present?
     end

data/lib/flow/operation/transactions.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# It's best practice to have Operations which modify several persisted objects to use a transaction.
+# Operations which modify several persisted objects together should use a transaction.
 module Operation
   module Transactions
     extend ActiveSupport::Concern

data/lib/flow/operation_base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "flow/errors/state_invalid"
+require_relative "operation/errors/already_executed"
+require_relative "operation/errors/already_rewound"
 
 require_relative "operation/callbacks"
 require_relative "operation/core"
@@ -11,7 +12,7 @@ require_relative "operation/rewind"
 require_relative "operation/status"
 require_relative "operation/transactions"
 
-# Operations are service objects which are executed with a state.
+# An **Operation** is a service object which is executed with a **State**.
 class OperationBase
   include ShortCircuIt
   include Technologic

data/lib/flow/state/attributes.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Defines the immutable structure by defining attribute accessors for the state data.
+# A state's attributes provide accessors to the input data it was initialized with.
 module State
   module Attributes
     extend ActiveSupport::Concern
@@ -25,6 +25,7 @@ module State
         attr_accessor attribute
         define_attribute_methods attribute
       end
+      alias_method :attribute, :define_attribute
     end
   end
 end

data/lib/flow/state/core.rb

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

data/lib/flow/state_base.rb

@@ -7,7 +7,7 @@ require_relative "state/options"
 require_relative "state/core"
 require_relative "state/string"
 
-# A flow state is the immutable structure of relevant data.
+# A **State** is an aggregation of input and derived data.
 class StateBase
   include ShortCircuIt
   include Technologic

data/lib/flow/version.rb

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

data/lib/generators/flow/state/templates/state.rb.erb

@@ -5,4 +5,5 @@ class <%= class_name %>State < ApplicationState
   # option :optional_input
   # option :option_with_default, default: :default_static_value
   # option(:option_with_default_from_block) { required_input.default_dynamic_value }
+  # attribute :some_runtime_value
 end

data/lib/generators/rspec/flow/templates/flow_spec.rb.erb

@@ -11,4 +11,18 @@ RSpec.describe <%= class_name %>Flow, type: :flow do
 
   it { is_expected.to inherit_from ApplicationFlow }
   # it { is_expected.to use_operations ExampleOperation }
+
+  describe "#trigger" do
+    subject(:trigger) { flow.trigger! }
+
+    pending "describe the effects of a successful `Flow#flux` (or delete) #{__FILE__}"
+  end
+
+  describe "#revert" do
+    before { flow.trigger! }
+
+    subject(:revert) { flow.revert }
+
+    pending "describe the effects of a successful `Flow#ebb` (or delete) #{__FILE__}"
+  end
 end

data/lib/generators/rspec/operation/templates/operation_spec.rb.erb

@@ -18,7 +18,17 @@ RSpec.describe <%= class_name %>, type: :operation do
 
   it { is_expected.to inherit_from ApplicationOperation }
 
-  describe "#execute" do
-    pending "add some examples to (or delete) #{__FILE__}"
+  describe "#execute!" do
+    subject(:execute!) { operation.execute! }
+
+    pending "describe `Operation#behavior` (or delete) #{__FILE__}"
+  end
+
+  describe "#rewind" do
+    before { operation.execute! }
+
+    subject(:execute!) { operation.rewind }
+
+    pending "describe `Operation#undo` (or delete) #{__FILE__}"
   end
 end

data/lib/generators/rspec/state/templates/state_spec.rb.erb

@@ -15,4 +15,5 @@ RSpec.describe <%= class_name %>State, type: :state do
   # it { is_expected.to define_option(:foo).with_default_value(:bar) }
   # it { is_expected.to define_option(:foo).with_default_value_block }
   # it { is_expected.to validate_presence_of ... }
+  # it { is_expected.to define_attribute :foo }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - Eric Garside
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-03 00:00:00.000000000 Z
+date: 2019-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -234,6 +234,7 @@ files:
 - lib/flow/concerns/transaction_wrapper.rb
 - lib/flow/custom_matchers.rb
 - lib/flow/custom_matchers/define_argument.rb
+- lib/flow/custom_matchers/define_attribute.rb
 - lib/flow/custom_matchers/define_option.rb
 - lib/flow/custom_matchers/use_operations.rb
 - lib/flow/flow/callbacks.rb
@@ -250,6 +251,8 @@ files:
 - lib/flow/operation/callbacks.rb
 - lib/flow/operation/core.rb
 - lib/flow/operation/error_handler.rb
+- lib/flow/operation/errors/already_executed.rb
+- lib/flow/operation/errors/already_rewound.rb
 - lib/flow/operation/execute.rb
 - lib/flow/operation/failures.rb
 - lib/flow/operation/rewind.rb