statesman 8.0.2 → 8.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b67b01e36452d54ed3a46731198cf31b62bc4b96c658f1555c1246a859a369a
-  data.tar.gz: d6bedd395500f7a079c8a7a3dda16c48f78b532dbd37bf9242644d1fb6f5186c
+  metadata.gz: 3d099ca7f60641163125a158ca189d41b571a46e4da8d5277a9391ff12df69e4
+  data.tar.gz: 5a33e698ded14cbc080f6d3e385d4d00d8191b5d1887e0b4fb062d592a35214f
 SHA512:
-  metadata.gz: 573dd79df9f8bbf958cfca8bd2a2477b10904916d43917fb269b41f154bde0f40e8bda641f5984c56772d1aa918bbfd84f8a14be881917370167ee1f3c4d6324
-  data.tar.gz: 9440bfaa20b003060c9dfa152d93c7142cff6ffa6ffc56ae52e966c1f96fdd95bd47d9e411987802bc986c7b6557223ce8696ffe446468735b360ed80d130ca3
+  metadata.gz: 1b7e63cd44278ca20c9aac95b6ff1372b83131d5df988b72d6fabfbbc98057917f33bc6cdbc447c2d1d04f075ac215e58eb5e0beb09d0fd7d2d16e672cebacd2
+  data.tar.gz: 63588d5869538bab0f4a7900f2761ed3bcfb124895485d2fc1667ec159763e4fad69327af25d7221f113f6c43396aabb3d8548085d6bb25229487c5d19ba11c0

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## UNRELEASED
+
+### Added
+- Implement `Machine#last_transition_to`, to find the last transition to a given state
+  [#xxx](https://github.com/gocardless/statesman/pull/xxx)
+
 ## v8.0.2 30th March 2021
 
 ### Changed

data/README.md

@@ -30,7 +30,7 @@ protection.
 To get started, just add Statesman to your `Gemfile`, and then run `bundle`:
 
 ```ruby
-gem 'statesman', '~> 7.1.0'
+gem 'statesman', '~> 8.0.3'
 ```
 
 ## Usage
@@ -109,6 +109,8 @@ Order.first.state_machine.allowed_transitions # => ["checking_out", "cancelled"]
 Order.first.state_machine.can_transition_to?(:cancelled) # => true/false
 Order.first.state_machine.transition_to(:cancelled, optional: :metadata) # => true/false
 Order.first.state_machine.transition_to!(:cancelled) # => true/exception
+Order.first.state_machine.last_transition # => transition model or nil
+Order.first.state_machine.last_transition_to(:pending) # => transition model or nil
 
 Order.in_state(:cancelled) # => [#<Order id: "123">]
 Order.not_in_state(:checking_out) # => [#<Order id: "123">]
@@ -159,7 +161,8 @@ class Order < ActiveRecord::Base
 
   # Optionally delegate some methods
 
-  delegate :can_transition_to?, :current_state, :history, :last_transition,
+  delegate :can_transition_to?,
+           :current_state, :history, :last_transition, :last_transition_to,
            :transition_to!, :transition_to, :in_state?, to: :state_machine
 end
 ```
@@ -335,6 +338,9 @@ Returns a sorted array of all transition objects.
 #### `Machine#last_transition`
 Returns the most recent transition object.
 
+#### `Machine#last_transition_to(:state)`
+Returns the most recent transition object to a given state.
+
 #### `Machine#allowed_transitions`
 Returns an array of states you can `transition_to` from current state.
 
@@ -351,6 +357,66 @@ Transition to the passed state, returning `true` on success. Swallows all
 Statesman exceptions and returns false on failure. (NB. if your guard or
 callback code throws an exception, it will not be caught.)
 
+
+## Errors
+
+### Initialization errors
+These errors are raised when the Machine and/or Model is initialized. A simple spec like
+```ruby
+expect { OrderStateMachine.new(Order.new, transition_class: OrderTransition) }.to_not raise_error
+```
+will expose these errors as part of your test suite
+
+#### InvalidStateError
+Raised if:
+  * Attempting to define a transition without a `to` state.
+  * Attempting to define a transition with a non-existent state.
+  * Attempting to define multiple states as `initial`.
+
+#### InvalidTransitionError
+Raised if:
+  * Attempting to define a callback `from` a state that has no valid transitions (A terminal state).
+  * Attempting to define a callback `to` the `initial` state if that state has no transitions to it.
+  * Attempting to define a callback with `from` and `to` where any of the pairs have no transition between them.
+
+#### InvalidCallbackError
+Raised if:
+  * Attempting to define a callback without a block.
+
+#### UnserializedMetadataError
+Raised if:
+  * ActiveRecord is configured to not serialize the `metadata` attribute into
+    to Database column backing it. See the `Using PostgreSQL JSON column` section.
+
+#### IncompatibleSerializationError
+Raised if:
+  * There is a mismatch between the column type of the `metadata` in the
+    Database and the model. See the `Using PostgreSQL JSON column` section.
+
+#### MissingTransitionAssociation
+Raised if:
+  * The model that `Statesman::Adapters::ActiveRecordQueries` is included in
+    does not have a `has_many` association to the `transition_class`.
+
+### Runtime errors
+These errors are raised by `transition_to!`. Using `transition_to` will
+supress `GuardFailedError` and `TransitionFailedError` and return `false` instead.
+
+#### GuardFailedError
+Raised if:
+  * A guard callback between `from` and `to` state returned a falsey value.
+
+#### TransitionFailedError
+Raised if:
+  * A transition is attempted but `current_state -> new_state` is not a valid pair.
+
+#### TransitionConflictError
+Raised if:
+  * A database conflict affecting the `sort_key` or `most_recent` columns occurs
+    when attempting a transition.
+    Retried automatically if it occurs wrapped in `retry_conflicts`.
+
+
 ## Model scopes
 
 A mixin is provided for the ActiveRecord adapter which adds scopes to easily

data/lib/statesman/machine.rb

@@ -209,6 +209,10 @@ module Statesman
       @storage_adapter.last(force_reload: force_reload)
     end
 
+    def last_transition_to(state)
+      history.reverse.find { |transition| transition.to_state.to_sym == state.to_sym }
+    end
+
     def can_transition_to?(new_state, metadata = {})
       validate_transition(from: current_state,
                           to: new_state,

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "8.0.2"
+  VERSION = "8.0.3"
 end

data/spec/statesman/machine_spec.rb

@@ -537,6 +537,34 @@ describe Statesman::Machine do
     end
   end
 
+  describe "#last_transition_to" do
+    subject { instance.last_transition_to(:y) }
+
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+        transition from: :z, to: :y
+      end
+
+      instance.transition_to!(:y)
+      instance.transition_to!(:z)
+    end
+
+    let(:instance) { machine.new(my_model) }
+
+    it { is_expected.to have_attributes(to_state: "y") }
+
+    context "when there are 2 transitions to the state" do
+      before { instance.transition_to!(:y) }
+
+      it { is_expected.to eq(instance.last_transition) }
+    end
+  end
+
   describe "#can_transition_to?" do
     subject(:can_transition_to?) { instance.can_transition_to?(new_state, metadata) }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 8.0.2
+  version: 8.0.3
 platform: ruby
 authors:
 - GoCardless
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-30 00:00:00.000000000 Z
+date: 2021-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ammeter