OSS Tanbou
View on GitHub

model states, events, and transitions as finite state machines in plain Ruby and ORM-backed classes

OSS scale score 250.3OSS health 70Update pace 0 commits/30d
About these scores

OSS scale score is an unbounded metric that log-compresses and weights Stars, Watchers, Forks, and Contributors. Discovery score is the current OSS scale score minus the score at discovery. Update pace is commits in the last 30 days, growth momentum is the OSS scale score difference within the recent observation window, and OSS health is a 0–100 rating based on available recency, Community Health, and release data.

Stars
5,229
Primary language
Ruby
License
MIT
Repository last updated
Jul 5, 2026
On this page

Overview

AASM is a Ruby library for embedding finite state machines in classes. It defines states, events, transitions, guards, and callbacks and can run in plain Ruby or integrate with persistence layers such as ActiveRecord and Mongoid. Domains such as orders, approvals, and jobs can keep transition rules and side effects close to the model.

Features and best fit

Based on official documentation; not hands-on tested · Content checked:

Key features

Define states, events, and transitions with a Ruby DSL

Models declare an initial state and other states, then define event transitions between them. AASM also generates helpers for checking the current state and whether an event may run.

Sources: [1]

Attach guards and callbacks to transition logic

Guards can control events and transitions, while before/after, state enter/exit, error, and related callbacks place notifications or other side effects around the lifecycle.

Sources: [1]

Connect state changes to ActiveRecord and other persistence adapters

Alongside plain Ruby, AASM supports ActiveRecord, Mongoid, Dynamoid, and other adapters. ActiveRecord integrations include persisted bang events, transactions, and pessimistic locking.

Sources: [1]

Best fit

Fits Ruby applications that need explicit model-level transition rules

It is useful for order statuses, approval flows, background-job stages, and similar domains where allowed transitions should be represented as one state machine instead of scattered conditional logic.

Sources: [1]

Before adoption

AASM 6 requires Ruby 3+ and Rails 7+ for ActiveRecord integration

The current source declares AASM 6.0.0, and the v5-to-v6 migration guide drops Ruby 2 and Rails 6 support. Confirm the application runtime before upgrading.

Sources: [2][4][3]

Namespaced event method names change from v5 behavior

In v6, a namespaced state machine no longer defines the plain event method and instead defines the namespace-suffixed method directly. Applications calling the old plain names need migration.

Sources: [4]

Persisted bang events now raise by default on persistence failure

Version 6 changes whiny_persistence to true by default, so a failed persisted bang event raises instead of silently returning false. Existing error handling should be reviewed.

Sources: [4]

Official sources

  1. [1]AASM README(2026-10-03)
  2. [2]AASM version source(2026-10-03)
  3. [3]AASM gemspec(2026-10-03)
  4. [4]AASM v5 to v6 migration guide(2026-10-03)
  5. [5]AASM MIT license(2026-10-03)
Supplemental curator note

AASM is useful for orders, approvals, jobs, and other domains where allowed state transitions should be explicit in Ruby code. Version 6 changes runtime requirements, namespaced event methods, and persistence-failure behavior, so a 5.x upgrade should be treated as a breaking migration.

Try it in 3 steps

  1. 1

    Add AASM to the Gemfile

    AASM 6 requires Ruby 3+, and its ActiveRecord integration requires Rails 7+. Check the application's runtime first.

    Add gem 'aasm' to Gemfile, then run bundle install
  2. 2

    Prepare a model with a state column

    Follow the documented generator workflow to prepare the model and migration. Review generated changes when applying it to an existing model.

    rails generate aasm Order state
  3. 3

    Define states and events, then test a transition

    Define states, events, and transitions and verify the current state and event execution in the console.

    Open app/models/order.rb, define the aasm block, then run rails console
Check the official README

Growth

Growth trends · Last 30 days

5,229 Stars

Trend data is still being collected.

Development activity

Last 90 days · weekly

Commits (last 30 days)
0
Open PRs
32

Development activity is still being collected.

Built with

Categories and tags

Categories

Tags

GitHub data

GitHub dataView detailed GitHub data
View on GitHub

GitHub Topics

  • state-machine
  • ruby
  • aasm
  • transition
  • activerecord
  • mongoid
  • hacktoberfest
  • rails
Stars
5,229
Forks
646
Watchers
59
Open issues
138
Contributors
179
Owner type
Organization
Primary language
Ruby
License
MIT
Repository last updated
Jul 5, 2026
Write a related article

Share a guide or use case for this OSS in Markdown. Articles are published after administrator approval.

Report incorrect information

Tell us if any listing information is incorrect or outdated.

After reading this page, do you know what to do next?