statesman 8.0.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeab084afcfb068e82eae390dbac202fb8167884b3a58610429ca2efb30a8b46
-  data.tar.gz: 65f10904ea38a716a26f7acd6d6809a484f4cb51eb5458b98f94d2b29acfd746
+  metadata.gz: 33b89c9b5c5c0a2e31706aedd4861e3c8967d82ec50a1571715d0b2029ed14d2
+  data.tar.gz: 8b201ea428387579869649c7739b393a4beaf6fb2b27070cd54202d7260fd6b4
 SHA512:
-  metadata.gz: 36a6a95abb071113a8a17e59982db8c0c1e82cd189d2b5c0d59e4825f894dfde59a0051357a935ff9c3070520541461a69177a08003c7734252c4c1ae42946b6
-  data.tar.gz: 96887197a7551e0fe65269b727cff3cba0318c459e895836d05969120cd22d6b17f1f9052935ce768f91ff4af9a0d33aff43af025e41bba28f24a1948e188056
+  metadata.gz: 0c29e6cf1d191c99d4867f5461ee859241873a00f7ee71730bed266a0e0ee07180acb16ff879f275cf789a33a7c67de73d5eafe04f5981b24ff1bb05ad876cab
+  data.tar.gz: 108e0c8b7c56cbac445e8c99708bd57b830325be91a40827a87ed51773c81165971cdf76ea446bdf6eb1b2fd19afe7accd6fba0b885824a30998212aa0492d85

data/.circleci/config.yml

@@ -1,187 +1,127 @@
 ---
-version: 2
+version: 2.1
 
 references:
-  steps: &steps
-    - checkout
-
-    - type: shell
-      name: Write RAILS_VERSION to a file so we can use it for caching purposes
-      command: echo "$RAILS_VERSION" > ~/RAILS_VERSION.txt
-
-    - type: cache-restore
-      key: statesman-{{ checksum "Gemfile" }}-{{ checksum "~/RAILS_VERSION.txt" }}
-
-    - run: gem install bundler -v 2.1.4
-
-    - run: bundle install --path vendor/bundle
+  bundle_install: &bundle_install
+    run:
+      name: Bundle
+      command: |
+        gem install bundler --no-document && \
+        bundle config set no-cache 'true' && \
+        bundle config set jobs '4' && \
+        bundle config set retry '3' && \
+        bundle install
 
-    - type: cache-save
-      key: statesman-{{ checksum "Gemfile" }}-{{ checksum "~/RAILS_VERSION.txt" }}
+  cache_bundle: &cache_bundle
+    save_cache:
+      key: bundle-<< parameters.ruby_version >>-<< parameters.rails_version >>-{{ checksum "statesman.gemspec" }}-{{ checksum "Gemfile" }}
       paths:
         - vendor/bundle
 
-    - run: bundle exec rubocop
+  restore_bundle: &restore_bundle
+    restore_cache:
+      key: bundle-<< parameters.ruby_version >>-<< parameters.rails_version >>-{{ checksum "statesman.gemspec" }}-{{ checksum "Gemfile" }}
 
+  steps: &steps
+    - add_ssh_keys
+    - checkout
+    - run:
+        name: "Add dependencies"
+        command: |
+          sudo apt-get update && sudo apt-get install -y sqlite3 libsqlite3-dev
+    - *restore_bundle
+    - *bundle_install
+    - *cache_bundle
     - run: dockerize -wait tcp://localhost:$DATABASE_DEPENDENCY_PORT -timeout 1m
+    - run:
+        name: Run specs
+        command: |
+          bundle exec rspec $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings) --profile --format progress --format RspecJunitFormatter -o /tmp/circle_artifacts/rspec.xml
+    - run:
+        name: "Rubocop"
+        command: bundle exec rubocop --extra-details --display-style-guide --parallel --force-exclusion
+    - store_artifacts:
+        path: /tmp/circle_artifacts/
+    - store_test_results:
+        path: /tmp/circle_artifacts/
 
-    - run: bundle exec rake
+  ruby_versions: &ruby_versions
+    - "2.5"
+    - "2.6"
+    - "2.7"
+    - "3.0"
 
-    - type: store_test_results
-      path: /tmp/test-results
+  rails_versions: &rails_versions
+    - "5.2.6"
+    - "6.0.4"
+    - "6.1.4"
+    - "main"
 
-jobs:
-  build-ruby249-rails-524-mysql:
-    docker:
-      - image: circleci/ruby:2.4.9-node
-        environment:
-          - RAILS_VERSION=5.2.4
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
-        environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
-    steps: *steps
-  build-ruby249-rails-524-postgres:
-    docker:
-      - image: circleci/ruby:2.4.9-node
-        environment:
-          - RAILS_VERSION=5.2.4
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
-        environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
-    steps: *steps
+  mysql_versions: &mysql_versions
+    - "5.7.18"
 
-  build-ruby265-rails-602-mysql:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=6.0.2
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
-        environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
-    steps: *steps
-  build-ruby265-rails-602-postgres:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=6.0.2
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
-        environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
-    steps: *steps
-  build-ruby265-rails-master-mysql:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
-        environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
-    steps: *steps
-  build-ruby265-rails-master-postgres:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
-        environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
-    steps: *steps
+  psql_versions: &psql_versions
+    - "9.6"
 
-  build-ruby270-rails-602-mysql:
-    docker:
-      - image: circleci/ruby:2.7.0-node
-        environment:
-          - RAILS_VERSION=6.0.2
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
-        environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
-    steps: *steps
-  build-ruby270-rails-602-postgres:
-    docker:
-      - image: circleci/ruby:2.7.0-node
-        environment:
-          - RAILS_VERSION=6.0.2
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
-        environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
-    steps: *steps
-  build-ruby270-rails-master-mysql:
+jobs:
+  rspec_mysql:
+    working_directory: /mnt/ramdisk
+    parameters:
+      ruby_version:
+        type: string
+      rails_version:
+        type: string
+      mysql_version:
+        type: string
     docker:
-      - image: circleci/ruby:2.7.0-node
+      - image: cimg/ruby:<< parameters.ruby_version >>
         environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
+          CIRCLE_TEST_REPORTS: /tmp/circle_artifacts/
+          DATABASE_URL: mysql2://foobar:password@127.0.0.1/statesman_test
+          DATABASE_DEPENDENCY_PORT: "3306"
+      - image: circleci/mysql:<< parameters.mysql_version >>
         environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
+          MYSQL_ROOT_PASSWORD: password
+          MYSQL_USER: foobar
+          MYSQL_PASSWORD: password
+          MYSQL_DATABASE: statesman_test
     steps: *steps
-  build-ruby270-rails-master-postgres:
+
+  rspec_postgres:
+    working_directory: /mnt/ramdisk
+    parameters:
+      ruby_version:
+        type: string
+      rails_version:
+        type: string
+      psql_version:
+        type: string
     docker:
-      - image: circleci/ruby:2.7.0-node
+      - image: cimg/ruby:<< parameters.ruby_version >>
         environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
+          CIRCLE_TEST_REPORTS: /tmp/circle_artifacts/
+          DATABASE_URL: postgres://postgres@localhost/statesman_test
+          DATABASE_DEPENDENCY_PORT: "5432"
+      - image: circleci/postgres:<< parameters.psql_version >>
         environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
+          POSTGRES_USER: postgres
+          POSTGRES_DB: statesman_test
+          POSTGRES_PASSWORD: statesman
     steps: *steps
 
 workflows:
   version: 2
   tests:
     jobs:
-      - build-ruby249-rails-524-mysql
-      - build-ruby249-rails-524-postgres
-      - build-ruby265-rails-602-mysql
-      - build-ruby265-rails-602-postgres
-      - build-ruby265-rails-master-mysql
-      - build-ruby265-rails-master-postgres
-      - build-ruby270-rails-602-mysql
-      - build-ruby270-rails-602-postgres
-      - build-ruby270-rails-master-mysql
-      - build-ruby270-rails-master-postgres
+      - rspec_mysql:
+          matrix:
+            parameters:
+              mysql_version: *mysql_versions
+              ruby_version: *ruby_versions
+              rails_version: *rails_versions
+      - rspec_postgres:
+          matrix:
+            parameters:
+              psql_version: *psql_versions
+              ruby_version: *ruby_versions
+              rails_version: *rails_versions

data/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+
+updates:
+  - package-ecosystem: bundler
+    directory: "/"
+    schedule:
+      interval: "daily"

data/.rubocop.yml

@@ -4,4 +4,4 @@ inherit_gem:
   gc_ruboconfig: rubocop.yml
 
 AllCops:
-  TargetRubyVersion: 2.4
+  TargetRubyVersion: 3.0

data/.rubocop_todo.yml

@@ -1,38 +1,42 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-08-17 15:19:58 +0100 using RuboCop version 0.61.1.
+# on 2021-08-09 15:32:40 UTC using RuboCop version 1.18.4.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 1
+# Configuration parameters: Include.
+# Include: **/*.gemspec
 Gemspec/RequiredRubyVersion:
-  Enabled: false # We want to allow Ruby 2.2 even though we don't test on it
+  Exclude:
+    - 'statesman.gemspec'
+
+# Offense count: 1
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/statesman/adapters/active_record_queries.rb'
 
 # Offense count: 5
+# Configuration parameters: IgnoredMethods, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 18
+  Max: 20
+
+# Offense count: 1
+# Configuration parameters: IgnoredMethods.
+Metrics/CyclomaticComplexity:
+  Max: 8
 
-# Offense count: 4
-# Configuration parameters: CountComments, ExcludedMethods.
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
   Max: 14
 
-# Offense count: 2
-# Cop supports --auto-correct.
-# Configuration parameters: SkipBlocks, EnforcedStyle.
-# SupportedStyles: described_class, explicit
-RSpec/DescribedClass:
-  Exclude:
-    - 'spec/statesman/adapters/active_record_queries_spec.rb'
-
-# Offense count: 7
-# Configuration parameters: Max.
+# Offense count: 11
+# Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Exclude:
-    - 'spec/statesman/adapters/active_record_spec.rb'
-    - 'spec/statesman/adapters/shared_examples.rb'
-    - 'spec/statesman/machine_spec.rb'
+  Max: 14
 
 # Offense count: 7
 RSpec/ExpectInHook:
@@ -40,11 +44,12 @@ RSpec/ExpectInHook:
     - 'spec/statesman/adapters/active_record_spec.rb'
     - 'spec/statesman/machine_spec.rb'
 
-# Offense count: 3
-RSpec/ImplicitBlockExpectation:
+# Offense count: 1
+# Configuration parameters: Include, CustomTransform, IgnoreMethods, SpecSuffixOnly.
+# Include: **/*_spec*rb*, **/spec/**/*
+RSpec/FilePath:
   Exclude:
-    - 'spec/statesman/adapters/active_record_spec.rb'
-    - 'spec/statesman/adapters/shared_examples.rb'
+    - 'spec/statesman/exceptions_spec.rb'
 
 # Offense count: 1
 # Configuration parameters: AssignmentOnly.
@@ -75,23 +80,27 @@ RSpec/MessageSpies:
   Exclude:
     - 'spec/statesman/callback_spec.rb'
 
-# Offense count: 9
-# Configuration parameters: AggregateFailuresByDefault.
+# Offense count: 14
 RSpec/MultipleExpectations:
   Max: 3
 
-# Offense count: 50
+# Offense count: 49
 RSpec/NestedGroups:
   Max: 6
 
-# Offense count: 16
+# Offense count: 2
+RSpec/RepeatedExampleGroupBody:
+  Exclude:
+    - 'spec/statesman/exceptions_spec.rb'
+
+# Offense count: 12
 RSpec/ScatteredSetup:
   Exclude:
     - 'spec/statesman/adapters/active_record_spec.rb'
     - 'spec/statesman/adapters/shared_examples.rb'
     - 'spec/statesman/machine_spec.rb'
 
-# Offense count: 8
+# Offense count: 7
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:

data/.ruby-version

@@ -0,0 +1 @@
+3.0.2

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## v9.0.0 9th August 2021
+
+### Added
+- Added Ruby 3.0 support
+
+### Breaking changes
+
+- Removed Ruby 2.4
+
+## v8.0.3 8th June 2021
+
+### Added
+- Implement `Machine#last_transition_to`, to find the last transition to a given state
+  [#438](https://github.com/gocardless/statesman/pull/438)
+
+## v8.0.2 30th March 2021
+
+### Changed
+
+- Fixed a bug where the `history` of a model was left in an incorrect state after a transition
+  conflict [#433](https://github.com/gocardless/statesman/pull/433)
+
+## v8.0.1 20th January 2021
+
+### Changed
+
+- Fixed `no implicit conversion of nil into String` error when quoting null values
+  [#427](https://github.com/gocardless/statesman/pull/427)
+
 ## v8.0.0 6th January 2021
 
 ### Added
@@ -24,16 +53,16 @@
 
 ### Changed
 
-- Use correct Arel for null [#409](https://github.com/gocardless/statesman/pull/#409)
+- Use correct Arel for null [#409](https://github.com/gocardless/statesman/pull/409)
 
 ## v7.2.0, 19th May 2020
 
 ### Changed
 
-- Set non-empty password for postgres tests [#398](https://github.com/gocardless/statesman/pull/#398)
-- Handle transitions differently for MySQL [#399](https://github.com/gocardless/statesman/pull/#399)
-- pg requirement from >= 0.18, <= 1.1 to >= 0.18, <= 1.3 [#400](https://github.com/gocardless/statesman/pull/#400)
-- Lazily enable mysql gaplock protection [#402](https://github.com/gocardless/statesman/pull/#402)
+- Set non-empty password for postgres tests [#398](https://github.com/gocardless/statesman/pull/398)
+- Handle transitions differently for MySQL [#399](https://github.com/gocardless/statesman/pull/399)
+- pg requirement from >= 0.18, <= 1.1 to >= 0.18, <= 1.3 [#400](https://github.com/gocardless/statesman/pull/400)
+- Lazily enable mysql gaplock protection [#402](https://github.com/gocardless/statesman/pull/402)
 
 ## v7.1.0, 10th Feb 2020
 
@@ -86,7 +115,7 @@
   to
   ```ruby
     include Statesman::Adapters::ActiveRecordQueries[
-      initial_state: :inital,
+      initial_state: :initial,
       transition_class: MyTransition
     ]
   ```

data/CONTRIBUTING.md

@@ -19,3 +19,21 @@ request passes by running `rubocop`.
 
 Please add a section to the readme for any new feature additions or behaviour
 changes.
+
+## Releasing
+
+We publish new versions of Stateman using [RubyGems](https://guides.rubygems.org/publishing/). Once
+the relevant changes have been merged and `VERSION` has been appropriately bumped to the new
+version, we run the following command.
+```
+$ gem build statesman.gemspec
+```
+This builds a `.gem` file locally that will be named something like `statesman-X` where `X` is the
+new version. For example, if we are releasing version 9.0.0, the file would be
+`statesman-9.0.0.gem`.
+
+To publish, run `gem push` with the new `.gem` file we just generated. This requires a OTP that is currently only available
+to GoCardless engineers. For example, if we were to continue to publish version 9.0.0, we would run:
+```
+$ gem push statesman-9.0.0.gem
+```

data/Gemfile

@@ -4,14 +4,11 @@ source 'https://rubygems.org'
 
 gemspec
 
-# rubocop:disable Bundler/DuplicatedGem
-if ENV['RAILS_VERSION'] == 'master'
-  gem "rails", git: "https://github.com/rails/rails"
+if ENV['RAILS_VERSION'] == 'main'
+  gem "rails", git: "https://github.com/rails/rails", branch: "main"
 elsif ENV['RAILS_VERSION']
   gem "rails", "~> #{ENV['RAILS_VERSION']}"
 end
-# rubocop:enable Bundler/DuplicatedGem
-
 group :development do
   # test/unit is no longer bundled with Ruby 2.2, but required by Rails
   gem "test-unit", "~> 3.3" if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.2.0")

data/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png" alt="Statesman"></p>
+<p align="center"><img src="https://user-images.githubusercontent.com/110275/106792848-96e4ee80-664e-11eb-8fd1-16ff24b41eb2.png" alt="Statesman" width="512"></p>
 
 A statesmanlike state machine library.
 
@@ -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
 ```
@@ -322,6 +325,10 @@ Machine.successors
 #### `Machine#current_state`
 Returns the current state based on existing transition objects.
 
+Takes an optional keyword argument to force a reload of data from the
+database.
+e.g `current_state(force_reload: true)`
+
 #### `Machine#in_state?(:state_1, :state_2, ...)`
 Returns true if the machine is in any of the given states.
 
@@ -331,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.
 
@@ -347,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/adapters/active_record.rb

@@ -42,7 +42,13 @@ module Statesman
       def create(from, to, metadata = {})
         create_transition(from.to_s, to.to_s, metadata)
       rescue ::ActiveRecord::RecordNotUnique => e
-        raise TransitionConflictError, e.message if transition_conflict_error? e
+        if transition_conflict_error? e
+          # The history has the invalid transition on the end of it, which means
+          # `current_state` would then be incorrect. We force a reload of the history to
+          # avoid this.
+          transitions_for_parent.reload
+          raise TransitionConflictError, e.message
+        end
 
         raise
       ensure
@@ -59,6 +65,7 @@ module Statesman
         end
       end
 
+      # rubocop:disable Naming/MemoizedInstanceVariableName
       def last(force_reload: false)
         if force_reload
           @last_transition = history(force_reload: true).last
@@ -66,6 +73,7 @@ module Statesman
           @last_transition ||= history.last
         end
       end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
 
       def reset
         @last_transition = nil
@@ -313,7 +321,7 @@ module Statesman
       end
 
       def db_null
-        type_cast(nil)
+        Arel::Nodes::SqlLiteral.new("NULL")
       end
 
       # Type casting against a column is deprecated and will be removed in Rails 6.2.

data/lib/statesman/exceptions.rb

@@ -2,9 +2,13 @@
 
 module Statesman
   class InvalidStateError < StandardError; end
+
   class InvalidTransitionError < StandardError; end
+
   class InvalidCallbackError < StandardError; end
+
   class TransitionConflictError < StandardError; end
+
   class MissingTransitionAssociation < StandardError; end
 
   class TransitionFailedError < StandardError

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.0"
+  VERSION = "9.0.0"
 end

data/spec/statesman/adapters/active_record_queries_spec.rb

@@ -50,10 +50,11 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
 
   shared_examples "testing methods" do
     before do
-      if config_type == :old
+      case config_type
+      when :old
         configure_old(MyActiveRecordModel, MyActiveRecordModelTransition)
         configure_old(OtherActiveRecordModel, OtherActiveRecordModelTransition)
-      elsif config_type == :new
+      when :new
         configure_new(MyActiveRecordModel, MyActiveRecordModelTransition)
         configure_new(OtherActiveRecordModel, OtherActiveRecordModelTransition)
       else
@@ -201,7 +202,6 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
         MyActiveRecordModel.create
       end
 
-      # rubocop:disable RSpec/ExampleLength
       it do
         expect do
           ActiveRecord::Base.transaction do
@@ -210,7 +210,6 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
           end
         end.to_not change(MyStateMachine, :after_commit_callback_executed)
       end
-      # rubocop:enable RSpec/ExampleLength
     end
   end
 

data/spec/statesman/adapters/active_record_spec.rb

@@ -130,6 +130,31 @@ describe Statesman::Adapters::ActiveRecord, active_record: true do
         expect { adapter.create(:y, :z) }.
           to raise_exception(Statesman::TransitionConflictError)
       end
+
+      it "does not pollute the state when the transition fails" do
+        # this increments the sort_key in the database
+        adapter.create(:x, :y)
+
+        # we then pre-load the transitions for efficiency
+        preloaded_model = MyActiveRecordModel.
+          includes(:my_active_record_model_transitions).
+          find(model.id)
+
+        adapter2 = described_class.
+          new(MyActiveRecordModelTransition, preloaded_model, observer)
+
+        # Now we generate a race
+        adapter.create(:y, :z)
+        expect { adapter2.create(:y, :a) }.
+          to raise_error(Statesman::TransitionConflictError)
+
+        # The preloaded adapter should discard the preloaded info
+        expect(adapter2.last).to have_attributes(to_state: "z")
+        expect(adapter2.history).to contain_exactly(
+          have_attributes(to_state: "y"),
+          have_attributes(to_state: "z"),
+        )
+      end
     end
 
     context "when other exceptions occur" do

data/spec/statesman/adapters/shared_examples.rb

@@ -128,6 +128,7 @@ shared_examples_for "an adapter" do |adapter_class, transition_class, options =
 
     it { is_expected.to be_a(transition_class) }
     specify { expect(adapter.last.to_state.to_sym).to eq(:z) }
+
     specify do
       expect(adapter.last(force_reload: true).to_state.to_sym).to eq(:z)
     end

data/spec/statesman/exceptions_spec.rb

@@ -7,6 +7,7 @@ describe Statesman do
     subject(:error) { Statesman::InvalidStateError.new }
 
     its(:message) { is_expected.to eq("Statesman::InvalidStateError") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -16,6 +17,7 @@ describe Statesman do
     subject(:error) { Statesman::InvalidTransitionError.new }
 
     its(:message) { is_expected.to eq("Statesman::InvalidTransitionError") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -25,6 +27,7 @@ describe Statesman do
     subject(:error) { Statesman::InvalidTransitionError.new }
 
     its(:message) { is_expected.to eq("Statesman::InvalidTransitionError") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -34,6 +37,7 @@ describe Statesman do
     subject(:error) { Statesman::TransitionConflictError.new }
 
     its(:message) { is_expected.to eq("Statesman::TransitionConflictError") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -43,6 +47,7 @@ describe Statesman do
     subject(:error) { Statesman::MissingTransitionAssociation.new }
 
     its(:message) { is_expected.to eq("Statesman::MissingTransitionAssociation") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -52,6 +57,7 @@ describe Statesman do
     subject(:error) { Statesman::TransitionFailedError.new("from", "to") }
 
     its(:message) { is_expected.to eq("Cannot transition from 'from' to 'to'") }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -63,6 +69,7 @@ describe Statesman do
     its(:message) do
       is_expected.to eq("Guard on transition from: 'from' to 'to' returned false")
     end
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -72,6 +79,7 @@ describe Statesman do
     subject(:error) { Statesman::UnserializedMetadataError.new("foo") }
 
     its(:message) { is_expected.to match(/foo#metadata is not serialized/) }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
@@ -81,6 +89,7 @@ describe Statesman do
     subject(:error) { Statesman::IncompatibleSerializationError.new("foo") }
 
     its(:message) { is_expected.to match(/foo#metadata column type cannot be json/) }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end

data/spec/statesman/machine_spec.rb

@@ -234,11 +234,9 @@ describe Statesman::Machine do
 
       it "does not add a callback" do
         expect do
-          begin
-            set_callback
-          rescue error_type
-            nil
-          end
+          set_callback
+        rescue error_type
+          nil
         end.to_not change(machine.callbacks[callback_store], :count)
       end
     end
@@ -537,6 +535,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) }
 

data/spec/support/active_record.rb

@@ -64,7 +64,7 @@ class CreateMyActiveRecordModelMigration < MIGRATION_CLASS
 end
 
 # TODO: make this a module we can extend from the app? Or a generator?
-# rubocop:disable MethodLength, Metrics/AbcSize
+# rubocop:disable Metrics/MethodLength
 class CreateMyActiveRecordModelTransitionMigration < MIGRATION_CLASS
   def change
     create_table :my_active_record_model_transitions do |t|
@@ -110,7 +110,7 @@ class CreateMyActiveRecordModelTransitionMigration < MIGRATION_CLASS
     end
   end
 end
-# rubocop:enable MethodLength, Metrics/AbcSize
+# rubocop:enable Metrics/MethodLength
 
 class OtherActiveRecordModel < ActiveRecord::Base
   has_many :other_active_record_model_transitions, autosave: false
@@ -144,7 +144,7 @@ class CreateOtherActiveRecordModelMigration < MIGRATION_CLASS
   end
 end
 
-# rubocop:disable MethodLength
+# rubocop:disable Metrics/MethodLength
 class CreateOtherActiveRecordModelTransitionMigration < MIGRATION_CLASS
   def change
     create_table :other_active_record_model_transitions do |t|
@@ -188,7 +188,7 @@ class CreateOtherActiveRecordModelTransitionMigration < MIGRATION_CLASS
     end
   end
 end
-# rubocop:enable MethodLength
+# rubocop:enable Metrics/MethodLength
 
 class DropMostRecentColumn < MIGRATION_CLASS
   def change
@@ -242,7 +242,7 @@ class CreateNamespacedARModelMigration < MIGRATION_CLASS
   end
 end
 
-# rubocop:disable MethodLength
+# rubocop:disable Metrics/MethodLength
 class CreateNamespacedARModelTransitionMigration < MIGRATION_CLASS
   def change
     create_table :my_namespace_my_active_record_model_transitions do |t|
@@ -282,5 +282,5 @@ class CreateNamespacedARModelTransitionMigration < MIGRATION_CLASS
                 name: "index_namespace_model_transitions_parent_latest"
     end
   end
-  # rubocop:enable MethodLength
+  # rubocop:enable Metrics/MethodLength
 end

data/statesman.gemspec

@@ -21,11 +21,11 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.2"
+  spec.required_ruby_version = ">= 2.5"
 
   spec.add_development_dependency "ammeter", "~> 1.1"
-  spec.add_development_dependency "bundler", "~> 2.1.4"
-  spec.add_development_dependency "gc_ruboconfig", "~> 2.3.9"
+  spec.add_development_dependency "bundler", "~> 2"
+  spec.add_development_dependency "gc_ruboconfig", "~> 2.26.0"
   spec.add_development_dependency "mysql2", ">= 0.4", "< 0.6"
   spec.add_development_dependency "pg", ">= 0.18", "<= 1.3"
   spec.add_development_dependency "pry"
@@ -33,8 +33,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0.0"
   spec.add_development_dependency "rspec", "~> 3.1"
   spec.add_development_dependency "rspec-its", "~> 1.1"
-  spec.add_development_dependency "rspec-rails", "~> 3.1"
   spec.add_development_dependency "rspec_junit_formatter", "~> 0.4.0"
+  spec.add_development_dependency "rspec-rails", "~> 3.1"
   spec.add_development_dependency "sqlite3", "~> 1.4.2"
   spec.add_development_dependency "timecop", "~> 0.9.1"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 8.0.0
+  version: 9.0.0
 platform: ruby
 authors:
 - GoCardless
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-06 00:00:00.000000000 Z
+date: 2021-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ammeter
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.4
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.4
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: gc_ruboconfig
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.9
+        version: 2.26.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.9
+        version: 2.26.0
 - !ruby/object:Gem::Dependency
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
@@ -163,33 +163,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec_junit_formatter
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 0.4.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
-  name: rspec_junit_formatter
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: '3.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -226,9 +226,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".github/dependabot.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
@@ -296,14 +298,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: A statesman-like state machine library