$ show gocardless/statesman
Statesman is a production-grade Ruby state machine library with a focus on audit trails, data integrity, and database-level uniqueness enforcement. The core is the `Statesman::Machine` module, which provides a declarative DSL (states, transitions, guards, before/after callbacks) and is mixed into a machine class per model. State transitions are persisted as separate transition records (via a pluggable storage adapter), enabling full history and metadata tracking. The library ships with two adapters: an in-memory adapter for testing and an ActiveRecord adapter that uses unique indexes on `sort_key` and `most_recent` columns to prevent duplicate transitions and provide efficient current-state queries. It includes query scopes (`in_state`, `not_in_state`) for ActiveRecord models, a denormalised cached-current-state feature via `ConfigureCachedCurrentState`, and a type-safe variant of the query module for Sorbet compatibility. The codebase is highly modular, well-tested (over 130 spec files across multiple database backends), and follows modern Ruby and Rails best practices. It is maintained by GoCardless and supports Ruby 3.3–4.0 and Rails 7.2–8.1.
The LLM identified 4 files worth highlighting for reuse:
Core module that provides the state machine DSL (states, transitions, guards, before/after callbacks). It handles validation of states and transitions, maintains callbacks organized by phase, and implements instance methods like `transition_to!`, `current_state`, and `allowed_transitions`. The retry-conflicts block and dynamic adapter selection are advanced features. This module is the heart of the library and demonstrates high craftsmanship in a declarative internal DSL.
ActiveRecord storage adapter that persists transitions with full audit history. Implements gaplock protection for MySQL, handles unique index violation detection (sort_key and most_recent), STI support, multi-database connections, and updates the denormalised cached_current_state column. The update logic for most_recent flags is optimised into a single SQL statement. This adapter is a reusable pattern for any Ruby ORM needing safe concurrent transition writes.
Provides `in_state` and `not_in_state` class methods on ActiveRecord models via a mixin. The `ClassMethods` module pattern allows configuration via `include Statesman::Adapters::ActiveRecordQueries[transition_class:, initial_state:]` with automatic inheritance handling. Builds a LEFT OUTER JOIN on the most_recent transition, accounting for initial state records. The query builder is self-contained and could be extracted as a generic pattern for adding scoped queries based on a related table's latest record.
A model mixin that maintains a denormalised current-state column on the parent model. The write is injected into the ActiveRecord adapter's `create_transition` method (not via a model callback), ensuring it fires reliably even under mysql gaplock protection where most_recent is flipped via raw SQL. Supports custom column names and optional `updated_at` touching. This component cleanly separates caching concerns from business logic and works correctly with multiple state machines per model.