{"id":13412055,"url":"https://github.com/aasm/aasm","last_synced_at":"2025-05-14T21:02:23.161Z","repository":{"id":384495,"uuid":"1734","full_name":"aasm/aasm","owner":"aasm","description":"AASM - State machines for Ruby classes (plain Ruby, ActiveRecord, Mongoid, NoBrainer, Dynamoid)","archived":false,"fork":false,"pushed_at":"2024-08-13T08:57:55.000Z","size":1973,"stargazers_count":5071,"open_issues_count":182,"forks_count":637,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-04-30T07:48:03.460Z","etag":null,"topics":["aasm","activerecord","hacktoberfest","mongoid","rails","ruby","state-machine","transition"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aasm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2008-02-28T20:40:04.000Z","updated_at":"2025-04-29T08:27:32.000Z","dependencies_parsed_at":"2024-05-01T13:20:01.607Z","dependency_job_id":"7a9b1b75-cce6-4667-b0b6-e881d60ea6b3","html_url":"https://github.com/aasm/aasm","commit_stats":{"total_commits":1222,"total_committers":237,"mean_commits":5.156118143459915,"dds":0.6153846153846154,"last_synced_commit":"666ef70c01aa69d458eb0bea36e36a5f4fcba8bd"},"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aasm%2Faasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aasm%2Faasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aasm%2Faasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aasm%2Faasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aasm","download_url":"https://codeload.github.com/aasm/aasm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252835437,"owners_count":21811538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aasm","activerecord","hacktoberfest","mongoid","rails","ruby","state-machine","transition"],"created_at":"2024-07-30T20:01:20.548Z","updated_at":"2025-05-07T07:39:51.789Z","avatar_url":"https://github.com/aasm.png","language":"Ruby","readme":"# AASM - Ruby state machines\n\n[![Gem Version](https://badge.fury.io/rb/aasm.svg)](http://badge.fury.io/rb/aasm)\n[![Build Status](https://github.com/aasm/aasm/actions/workflows/build.yml/badge.svg)](https://github.com/aasm/aasm/actions/workflows/build.yml)\n[![Code Climate](https://codeclimate.com/github/aasm/aasm/badges/gpa.svg)](https://codeclimate.com/github/aasm/aasm)\n[![codecov](https://codecov.io/gh/aasm/aasm/branch/master/graph/badge.svg)](https://codecov.io/gh/aasm/aasm)\n\n## Index\n- [Upgrade from version 3 to 4](#upgrade-from-version-3-to-4)\n- [Usage](#usage)\n  - [Callbacks](#callbacks)\n    - [Lifecycle](#lifecycle)\n    - [The current event triggered](#the-current-event-triggered)\n  - [Guards](#guards)\n  - [Transitions](#transitions)\n  - [Multiple state machines per class](#multiple-state-machines-per-class)\n    - [Handling naming conflicts between multiple state machines](#handling-naming-conflicts-between-multiple-state-machines)\n    - [Binding event](#binding-event)\n  - [Auto-generated Status Constants](#auto-generated-status-constants)\n  - [Extending AASM](#extending-aasm)\n  - [ActiveRecord](#activerecord)\n  - [Bang events](#bang-events)\n  - [Timestamps](#timestamps)\n  - [ActiveRecord enums](#activerecord-enums)\n  - [Sequel](#sequel)\n  - [Dynamoid](#dynamoid)\n  - [Mongoid](#mongoid)\n  - [Nobrainer](#nobrainer)\n  - [Redis](#redis)\n  - [Automatic Scopes](#automatic-scopes)\n  - [Transaction support](#transaction-support)\n  - [Pessimistic Locking](#pessimistic-locking)\n  - [Column name \u0026 migration](#column-name--migration)\n  - [Log State Changes](#log-state-changes)\n  - [Inspection](#inspection)\n  - [Warning output](#warning-output)\n  - [RubyMotion support](#rubymotion-support)\n  - [Testing](#testing)\n    - [RSpec](#rspec)\n    - [Minitest](#minitest)\n      - [Assertions](#assertions)\n      - [Expectations](#expectations)\n - [Installation](#installation)\n   - [Manually from RubyGems.org](#manually-from-rubygemsorg)\n   - [Bundler](#or-if-you-are-using-bundler)\n   - [Building your own gems](#building-your-own-gems)\n  - [Generators](#generators)\n  - [Test suite with Docker](#docker)\n  - [Latest changes](#latest-changes)\n  - [Questions?](#questions)\n  - [Maintainers](#maintainers)\n- [Contributing](CONTRIBUTING.md)\n- [Warranty](#warranty)\n- [License](#license)\n\nThis package contains AASM, a library for adding finite state machines to Ruby classes.\n\nAASM started as the *acts_as_state_machine* plugin but has evolved into a more generic library\nthat no longer targets only ActiveRecord models. It currently provides adapters for many\nORMs but it can be used for any Ruby class, no matter what parent class it has (if any).\n\n## Upgrade from version 3 to 4\n\nTake a look at the [README_FROM_VERSION_3_TO_4](https://github.com/aasm/aasm/blob/master/README_FROM_VERSION_3_TO_4.md) for details how to switch from version 3.x to 4.0 of _AASM_.\n\n## Usage\n\nAdding a state machine is as simple as including the AASM module and start defining\n**states** and **events** together with their **transitions**:\n\n```ruby\nclass Job\n  include AASM\n\n  aasm do\n    state :sleeping, initial: true\n    state :running, :cleaning\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n\n    event :clean do\n      transitions from: :running, to: :cleaning\n    end\n\n    event :sleep do\n      transitions from: [:running, :cleaning], to: :sleeping\n    end\n  end\n\nend\n```\n\nThis provides you with a couple of public methods for instances of the class `Job`:\n\n```ruby\njob = Job.new\njob.sleeping? # =\u003e true\njob.may_run?  # =\u003e true\njob.run\njob.running?  # =\u003e true\njob.sleeping? # =\u003e false\njob.may_run?  # =\u003e false\njob.run       # =\u003e raises AASM::InvalidTransition\n```\n\nIf you don't like exceptions and prefer a simple `true` or `false` as response, tell\nAASM not to be *whiny*:\n\n```ruby\nclass Job\n  ...\n  aasm whiny_transitions: false do\n    ...\n  end\nend\n\njob.running?  # =\u003e true\njob.may_run?  # =\u003e false\njob.run       # =\u003e false\n```\n\nWhen firing an event, you can pass a block to the method, it will be called only if\nthe transition succeeds :\n\n```ruby\n  job.run do\n    job.user.notify_job_ran # Will be called if job.may_run? is true\n  end\n```\n\n### Callbacks\n\nYou can define a number of callbacks for your events, transitions and states. These methods, Procs or classes will be\ncalled when certain criteria are met, like entering a particular state:\n\n```ruby\nclass Job\n  include AASM\n\n  aasm do\n    state :sleeping, initial: true, before_enter: :do_something\n    state :running, before_enter: Proc.new { do_something \u0026\u0026 notify_somebody }\n    state :finished\n\n    after_all_transitions :log_status_change\n\n    event :run, after: :notify_somebody do\n      before do\n        log('Preparing to run')\n      end\n\n      transitions from: :sleeping, to: :running, after: Proc.new {|*args| set_process(*args) }\n      transitions from: :running, to: :finished, after: LogRunTime\n    end\n\n    event :sleep do\n      after do\n        ...\n      end\n      error do |e|\n        ...\n      end\n      transitions from: :running, to: :sleeping\n    end\n  end\n\n  def log_status_change\n    puts \"changing from #{aasm.from_state} to #{aasm.to_state} (event: #{aasm.current_event})\"\n  end\n\n  def set_process(name)\n    ...\n  end\n\n  def do_something\n    ...\n  end\n\n  def notify_somebody\n    ...\n  end\n\nend\n\nclass LogRunTime\n  def call\n    log \"Job was running for X seconds\"\n  end\nend\n```\n\nIn this case `do_something` is called before actually entering the state `sleeping`,\nwhile `notify_somebody` is called after the transition `run` (from `sleeping` to `running`)\nis finished.\n\nAASM will also initialize `LogRunTime` and run the `call` method for you after the transition from `running` to `finished` in the example above. You can pass arguments to the class by defining an initialize method on it, like this:\n\nNote that Procs are executed in the context of a record, it means that you don't need to expect the record as an argument, just call the methods you need.\n\n```ruby\nclass LogRunTime\n  # optional args parameter can be omitted, but if you define initialize\n  # you must accept the model instance as the first parameter to it.\n  def initialize(job, args = {})\n    @job = job\n  end\n\n  def call\n    log \"Job was running for #{@job.run_time} seconds\"\n  end\nend\n```\n\n#### Parameters\nYou can pass parameters to events:\n\n```ruby\n  job = Job.new\n  job.run(:defragmentation)\n```\n\nAll guards and after callbacks will receive these parameters. In this case `set_process` would be called with\n`:defragmentation` argument.\n\nIf the first argument to the event is a state (e.g. `:running` or `:finished`), the first argument is consumed and\nthe state machine will attempt to transition to that state. Add comma separated parameter for guards and callbacks\n\n```ruby\n  job = Job.new\n  job.run(:running, :defragmentation)\n```\nIn this case `set_process` won't be called, job will transition to running state and callback will receive\n`:defragmentation` as parameter\n\n#### Error Handling\nIn case of an error during the event processing the error is rescued and passed to `:error`\ncallback, which can handle it or re-raise it for further propagation.\n\nAlso, you can define a method that will be called if any event fails:\n\n```ruby\ndef aasm_event_failed(event_name, old_state_name)\n  # use custom exception/messages, report metrics, etc\nend\n```\n\nDuring the transition's `:after` callback (and reliably only then, or in the global\n`after_all_transitions` callback) you can access the originating state (the from-state)\nand the target state (the to state), like this:\n\n```ruby\n  def set_process(name)\n    logger.info \"from #{aasm.from_state} to #{aasm.to_state}\"\n  end\n```\n\n#### Lifecycle\n\nHere you can see a list of all possible callbacks, together with their order of calling:\n\n```ruby\nbegin\n  event           before_all_events\n  event           before\n  event           guards\n  transition      guards\n  old_state       before_exit\n  old_state       exit\n                  after_all_transitions\n  transition      after\n  new_state       before_enter\n  new_state       enter\n  ...update state...\n  event           before_success      # if persist successful\n  transition      success             # if persist successful, database update not guaranteed\n  event           success             # if persist successful, database update not guaranteed\n  old_state       after_exit\n  new_state       after_enter\n  event           after\n  event           after_all_events\nrescue\n  event           error\n  event           error_on_all_events\nensure\n  event           ensure\n  event           ensure_on_all_events\nend\n```\n\nUse event's `after_commit` callback if it should be fired after database update.\n\n#### The current event triggered\n\nWhile running the callbacks you can easily retrieve the name of the event triggered\nby using `aasm.current_event`:\n\n```ruby\n  # taken the example callback from above\n  def do_something\n    puts \"triggered #{aasm.current_event}\"\n  end\n```\n\nand then\n\n```ruby\n  job = Job.new\n\n  # without bang\n  job.sleep # =\u003e triggered :sleep\n\n  # with bang\n  job.sleep! # =\u003e triggered :sleep!\n```\n\n\n### Guards\n\nLet's assume you want to allow particular transitions only if a defined condition is\ngiven. For this you can set up a guard per transition, which will run before actually\nrunning the transition. If the guard returns `false` the transition will be\ndenied (raising `AASM::InvalidTransition`):\n\n```ruby\nclass Cleaner\n  include AASM\n\n  aasm do\n    state :idle, initial: true\n    state :cleaning\n\n    event :clean do\n      transitions from: :idle, to: :cleaning, guard: :cleaning_needed?\n    end\n\n    event :clean_if_needed do\n      transitions from: :idle, to: :cleaning do\n        guard do\n          cleaning_needed?\n        end\n      end\n      transitions from: :idle, to: :idle\n    end\n\n    event :clean_if_dirty do\n      transitions from: :idle, to: :cleaning, guard: :if_dirty?\n    end\n  end\n\n  def cleaning_needed?\n    false\n  end\n\n  def if_dirty?(status)\n    status == :dirty\n  end\nend\n\njob = Cleaner.new\njob.may_clean?            # =\u003e false\njob.clean                 # =\u003e raises AASM::InvalidTransition\njob.may_clean_if_needed?  # =\u003e true\njob.clean_if_needed!      # idle\n\njob.clean_if_dirty(:clean) # =\u003e raises AASM::InvalidTransition\njob.clean_if_dirty(:dirty) # =\u003e true\n```\n\nYou can even provide a number of guards, which all have to succeed to proceed\n\n```ruby\n    def walked_the_dog?; ...; end\n\n    event :sleep do\n      transitions from: :running, to: :sleeping, guards: [:cleaning_needed?, :walked_the_dog?]\n    end\n```\n\nIf you want to provide guards for all transitions within an event, you can use event guards\n\n```ruby\n    event :sleep, guards: [:walked_the_dog?] do\n      transitions from: :running, to: :sleeping, guards: [:cleaning_needed?]\n      transitions from: :cleaning, to: :sleeping\n    end\n```\n\nIf you prefer a more Ruby-like guard syntax, you can use `if` and `unless` as well:\n\n```ruby\n    event :clean do\n      transitions from: :running, to: :cleaning, if: :cleaning_needed?\n    end\n\n    event :sleep do\n      transitions from: :running, to: :sleeping, unless: :cleaning_needed?\n    end\n  end\n```\n\nYou can invoke a Class instead of a method if the Class responds to `call`\n\n```ruby\n    event :sleep do\n      transitions from: :running, to: :sleeping, guards: Dog\n    end\n```\n```ruby\n  class Dog\n    def call\n      cleaning_needed? \u0026\u0026 walked?\n    end\n    ...\n  end\n```\n\n### Transitions\n\nIn the event of having multiple transitions for an event, the first transition that successfully completes will stop other transitions in the same event from being processed.\n\n```ruby\nrequire 'aasm'\n\nclass Job\n  include AASM\n\n  aasm do\n    state :stage1, initial: true\n    state :stage2\n    state :stage3\n    state :completed\n\n    event :stage1_completed do\n      transitions from: :stage1, to: :stage3, guard: :stage2_completed?\n      transitions from: :stage1, to: :stage2\n    end\n  end\n\n  def stage2_completed?\n    true\n  end\nend\n\njob = Job.new\njob.stage1_completed\njob.aasm.current_state # stage3\n```\n\nYou can define transition from any defined state by omitting `from`:\n\n```ruby\nevent :abort do\n  transitions to: :aborted\nend\n```\n\n### Display name for state\n\nYou can define display name for state using :display option\n\n```ruby\nclass Job\n  include AASM\n\n  aasm do\n    state :stage1, initial: true, display: 'First Stage'\n    state :stage2\n    state :stage3\n  end\nend\n\njob = Job.new\njob.aasm.human_state\n\n```\n\n### Multiple state machines per class\n\nMultiple state machines per class are supported. Be aware though that _AASM_ has been\nbuilt with one state machine per class in mind. Nonetheless, here's how to do it (see below). Please note that you will need to specify database columns for where your pertinent states will be stored - we have specified two columns `move_state` and `work_state` in the example below. See the [Column name \u0026 migration](https://github.com/aasm/aasm#column-name--migration) section for further info.\n\n```ruby\nclass SimpleMultipleExample\n  include AASM\n  aasm(:move, column: 'move_state') do\n    state :standing, initial: true\n    state :walking\n    state :running\n\n    event :walk do\n      transitions from: :standing, to: :walking\n    end\n    event :run do\n      transitions from: [:standing, :walking], to: :running\n    end\n    event :hold do\n      transitions from: [:walking, :running], to: :standing\n    end\n  end\n\n  aasm(:work, column: 'work_state') do\n    state :sleeping, initial: true\n    state :processing\n\n    event :start do\n      transitions from: :sleeping, to: :processing\n    end\n    event :stop do\n      transitions from: :processing, to: :sleeping\n    end\n  end\nend\n\nsimple = SimpleMultipleExample.new\n\nsimple.aasm(:move).current_state\n# =\u003e :standing\nsimple.aasm(:work).current_state\n# =\u003e :sleeping\n\nsimple.start\nsimple.aasm(:move).current_state\n# =\u003e :standing\nsimple.aasm(:work).current_state\n# =\u003e :processing\n\n```\n\n#### Handling naming conflicts between multiple state machines\n\n_AASM_ doesn't prohibit to define the same event in more than one state\nmachine. If no namespace is provided, the latest definition \"wins\" and\noverrides previous definitions. Nonetheless, a warning is issued:\n`SimpleMultipleExample: overriding method 'run'!`.\n\nAlternatively, you can provide a namespace for each state machine:\n\n```ruby\nclass NamespacedMultipleExample\n  include AASM\n  aasm(:status) do\n    state :unapproved, initial: true\n    state :approved\n\n    event :approve do\n      transitions from: :unapproved, to: :approved\n    end\n\n    event :unapprove do\n      transitions from: :approved, to: :unapproved\n    end\n  end\n\n  aasm(:review_status, namespace: :review) do\n    state :unapproved, initial: true\n    state :approved\n\n    event :approve do\n      transitions from: :unapproved, to: :approved\n    end\n\n    event :unapprove do\n      transitions from: :approved, to: :unapproved\n    end\n  end\nend\n\nnamespaced = NamespacedMultipleExample.new\n\nnamespaced.aasm(:status).current_state\n# =\u003e :unapproved\nnamespaced.aasm(:review_status).current_state\n# =\u003e :unapproved\nnamespaced.approve_review\nnamespaced.aasm(:review_status).current_state\n# =\u003e :approved\n```\n\nAll _AASM_ class- and instance-level `aasm` methods accept a state machine selector.\nSo, for example, to use inspection on a class level, you have to use\n\n```ruby\nSimpleMultipleExample.aasm(:move).states.map(\u0026:name)\n# =\u003e [:standing, :walking, :running]\n```\n\n### Binding event\n\nAllow an event to be bound to another\n```ruby\nclass Example\n  include AASM\n\n  aasm(:work) do\n    state :sleeping, initial: true\n    state :processing\n\n    event :start do\n      transitions from: :sleeping, to: :processing\n    end\n    event :stop do\n      transitions from: :processing, to: :sleeping\n    end\n  end\n\n  aasm(:question) do\n    state :answered, initial: true\n    state :asked\n\n    event :ask, binding_event: :start do\n      transitions from: :answered, to: :asked\n    end\n    event :answer, binding_event: :stop do\n      transitions from: :asked, to: :answered\n    end\n  end\nend\n\nexample = Example.new\nexample.aasm(:work).current_state #=\u003e :sleeping\nexample.aasm(:question).current_state #=\u003e :answered\nexample.ask\nexample.aasm(:work).current_state #=\u003e :processing\nexample.aasm(:question).current_state #=\u003e :asked\n```\n\n### Auto-generated Status Constants\n\nAASM automatically [generates constants](https://github.com/aasm/aasm/pull/60)\nfor each status so you don't have to explicitly define them.\n\n```ruby\nclass Foo\n  include AASM\n\n  aasm do\n    state :initialized\n    state :calculated\n    state :finalized\n  end\nend\n\n\u003e Foo::STATE_INITIALIZED\n#=\u003e :initialized\n\u003e Foo::STATE_CALCULATED\n#=\u003e :calculated\n```\n\n### Extending AASM\n\nAASM allows you to easily extend `AASM::Base` for your own application purposes.\n\nLet's suppose we have common logic across many AASM models. We can embody this logic in a sub-class of `AASM::Base`.\n\n```ruby\nclass CustomAASMBase \u003c AASM::Base\n  # A custom transition that we want available across many AASM models.\n  def count_transitions!\n    klass.class_eval do\n      aasm with_klass: CustomAASMBase do\n        after_all_transitions :increment_transition_count\n      end\n    end\n  end\n\n  # A custom annotation that we want available across many AASM models.\n  def requires_guards!\n    klass.class_eval do\n      attr_reader :authorizable_called,\n        :transition_count,\n        :fillable_called\n\n      def authorizable?\n        @authorizable_called = true\n      end\n\n      def fillable?\n        @fillable_called = true\n      end\n\n      def increment_transition_count\n        @transition_count ||= 0\n        @transition_count += 1\n      end\n    end\n  end\nend\n```\n\nWhen we declare our model that has an AASM state machine, we simply declare the AASM block with a `:with_klass` key to our own class.\n\n```ruby\nclass SimpleCustomExample\n  include AASM\n\n  # Let's build an AASM state machine with our custom class.\n  aasm with_klass: CustomAASMBase do\n    requires_guards!\n    count_transitions!\n\n    state :initialised, initial: true\n    state :filled_out\n    state :authorised\n\n    event :fill_out do\n      transitions from: :initialised, to: :filled_out, guard: :fillable?\n    end\n    event :authorise do\n      transitions from: :filled_out, to: :authorised, guard: :authorizable?\n    end\n  end\nend\n```\n\n\n### ActiveRecord\n\nAASM comes with support for ActiveRecord and allows automatic persisting of the object's\nstate in the database.\n\nAdd `gem 'after_commit_everywhere', '~\u003e 1.0'` to your Gemfile.\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm do # default column: aasm_state\n    state :sleeping, initial: true\n    state :running\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n\n    event :sleep do\n      transitions from: :running, to: :sleeping\n    end\n  end\n\nend\n```\n\n### Bang events\n\nYou can tell AASM to auto-save the object or leave it unsaved\n\n```ruby\njob = Job.new\njob.run   # not saved\njob.run!  # saved\n\n# or\njob.aasm.fire(:run) # not saved\njob.aasm.fire!(:run) # saved\n```\n\nSaving includes running all validations on the `Job` class. If\n`whiny_persistence` flag is set to `true`, exception is raised in case of\nfailure. If `whiny_persistence` flag is set to `false`, methods with a bang return\n`true` if the state transition is successful or `false` if an error occurs.\n\nIf you want make sure the state gets saved without running validations (and\nthereby maybe persisting an invalid object state), simply tell AASM to skip the\nvalidations. Be aware that when skipping validations, only the state column will\nbe updated in the database (just like ActiveRecord `update_column` is working).\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm skip_validation_on_save: true do\n    state :sleeping, initial: true\n    state :running\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n\n    event :sleep do\n      transitions from: :running, to: :sleeping\n    end\n  end\n\nend\n```\n\nAlso, you can skip the validation at instance level with `some_event_name_without_validation!` method.\nWith this you have the flexibility of having validation for all your transitions by default and then skip it wherever required.\nPlease note that only state column will be updated as mentioned in the above example.\n\n```ruby\njob.run_without_validation!\n```\n\nIf you want to make sure that the _AASM_ column for storing the state is not directly assigned,\nconfigure _AASM_ to not allow direct assignment, like this:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm no_direct_assignment: true do\n    state :sleeping, initial: true\n    state :running\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n  end\n\nend\n```\n\nresulting in this:\n\n```ruby\njob = Job.create\njob.aasm_state # =\u003e 'sleeping'\njob.aasm_state = :running # =\u003e raises AASM::NoDirectAssignmentError\njob.aasm_state # =\u003e 'sleeping'\n```\n\n### Timestamps\n\nYou can tell _AASM_ to try to write a timestamp whenever a new state is entered.\nIf `timestamps: true` is set, _AASM_ will look for a field named like the new state plus `_at` and try to fill it:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm timestamps: true do\n    state :sleeping, initial: true\n    state :running\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n  end\nend\n```\n\nresulting in this:\n\n```ruby\njob = Job.create\njob.running_at # =\u003e nil\njob.run!\njob.running_at # =\u003e 2020-02-20 20:00:00\n```\n\nMissing timestamp fields are silently ignored, so it is not necessary to have setters (such as ActiveRecord columns) for *all* states when using this option.\n\n#### ActiveRecord enums\n\nYou can use\n[enumerations](http://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html)\nin Rails 4.1+ for your state column:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  enum state: {\n    sleeping: 5,\n    running: 99\n  }\n\n  aasm column: :state, enum: true do\n    state :sleeping, initial: true\n    state :running\n  end\nend\n```\n\nYou can explicitly pass the name of the method which provides access\nto the enumeration mapping as a value of ```enum```, or you can simply\nset it to ```true```. In the latter case AASM will try to use\npluralized column name to access possible enum states.\n\nFurthermore, if your column has integer type (which is normally the\ncase when you're working with Rails enums), you can omit ```:enum```\nsetting --- AASM auto-detects this situation and enabled enum\nsupport. If anything goes wrong, you can disable enum functionality\nand fall back to the default behavior by setting ```:enum```\nto ```false```.\n\n### Sequel\n\nAASM also supports [Sequel](http://sequel.jeremyevans.net/) besides _ActiveRecord_, and _Mongoid_.\n\n```ruby\nclass Job \u003c Sequel::Model\n  include AASM\n\n  aasm do # default column: aasm_state\n    ...\n  end\nend\n```\n\nHowever it's not yet as feature complete as _ActiveRecord_. For example, there are\nscopes defined yet. See [Automatic Scopes](#automatic-scopes).\n\n### Dynamoid\n\nSince version `4.8.0` _AASM_ also supports [Dynamoid](http://joshsymonds.com/Dynamoid/) as\npersistence ORM.\n\n### Mongoid\n\nAASM also supports persistence to Mongodb if you're using Mongoid. Make sure\nto include Mongoid::Document before you include AASM.\n\n```ruby\nclass Job\n  include Mongoid::Document\n  include AASM\n  field :aasm_state\n  aasm do\n    ...\n  end\nend\n```\n\n### NoBrainer\n\nAASM also supports persistence to [RethinkDB](https://www.rethinkdb.com/)\nif you're using [Nobrainer](http://nobrainer.io/).\nMake sure to include NoBrainer::Document before you include AASM.\n\n```ruby\nclass Job\n  include NoBrainer::Document\n  include AASM\n  field :aasm_state\n  aasm do\n    ...\n  end\nend\n```\n\n### Redis\n\nAASM also supports persistence in Redis via\n[Redis::Objects](https://github.com/nateware/redis-objects).\nMake sure to include Redis::Objects before you include AASM. Note that non-bang\nevents will work as bang events, persisting the changes on every call.\n\n```ruby\nclass User\n  include Redis::Objects\n  include AASM\n\n  aasm do\n  end\nend\n```\n\n### Automatic Scopes\n\nAASM will automatically create scope methods for each state in the model.\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm do\n    state :sleeping, initial: true\n    state :running\n    state :cleaning\n  end\n\n  def self.sleeping\n    \"This method name is already in use\"\n  end\nend\n```\n\n```ruby\nclass JobsController \u003c ApplicationController\n  def index\n    @running_jobs = Job.running\n    @recent_cleaning_jobs = Job.cleaning.where('created_at \u003e=  ?', 3.days.ago)\n\n    # @sleeping_jobs = Job.sleeping   #=\u003e \"This method name is already in use\"\n  end\nend\n```\n\nIf you don't need scopes (or simply don't want them), disable their creation when\ndefining the `AASM` states, like this:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm create_scopes: false do\n    state :sleeping, initial: true\n    state :running\n    state :cleaning\n  end\nend\n```\n\n\n### Transaction support\n\nSince version *3.0.13* AASM supports ActiveRecord transactions. So whenever a transition\ncallback or the state update fails, all changes to any database record are rolled back.\nMongodb does not support transactions.\n\nThere are currently 3 transactional callbacks that can be handled on the event, and 2 transactional callbacks for all events.\n\n```ruby\n  event           before_all_transactions\n  event           before_transaction\n  event           aasm_fire_event (within transaction)\n  event           after_commit (if event successful)\n  event           after_transaction\n  event           after_all_transactions\n```\n\nIf you want to make sure a depending action happens only after the transaction is committed,\nuse the `after_commit` callback along with the auto-save (bang) methods, like this:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm do\n    state :sleeping, initial: true\n    state :running\n\n    event :run, after_commit: :notify_about_running_job do\n      transitions from: :sleeping, to: :running\n    end\n  end\n\n  def notify_about_running_job\n    ...\n  end\nend\n\njob = Job.where(state: 'sleeping').first!\njob.run! # Saves the model and triggers the after_commit callback\n```\n\nNote that the following will not run the `after_commit` callbacks because\nthe auto-save method is not used:\n\n```ruby\njob = Job.where(state: 'sleeping').first!\njob.run\njob.save! #notify_about_running_job is not run\n```\n\nPlease note that `:after_commit` AASM callbacks behaves around custom implementation\nof transaction pattern rather than a real-life DB transaction. This fact still causes\nthe race conditions and redundant callback calls within nested transaction. In order\nto fix that it's highly recommended to add `gem 'after_commit_everywhere', '~\u003e 1.0'`\nto your `Gemfile`.\n\nIf you want to encapsulate state changes within an own transaction, the behavior\nof this nested transaction might be confusing. Take a look at\n[ActiveRecord Nested Transactions](http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html)\nif you want to know more about this. Nevertheless, AASM by default requires a new transaction\n`transaction(requires_new: true)`. You can override this behavior by changing\nthe configuration\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm requires_new_transaction: false do\n    ...\n  end\n\n  ...\nend\n```\n\nwhich then leads to `transaction(requires_new: false)`, the Rails default.\n\nAdditionally, if you do not want any of your ActiveRecord actions to be\nwrapped in a transaction, you can specify the `use_transactions` flag. This can\nbe useful if you want want to persist things to the database that happen as a\nresult of a transaction or callback, even when some error occurs. The\n`use_transactions` flag is true by default.\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm use_transactions: false do\n    ...\n  end\n\n  ...\nend\n```\n\n### Pessimistic Locking\n\nAASM supports [ActiveRecord pessimistic locking via `with_lock`](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Pessimistic.html#method-i-with_lock) for database persistence layers.\n\n| Option | Purpose |\n| ------ | ------- |\n| `false` (default) | No lock is obtained | |\n| `true` | Obtain a blocking pessimistic lock e.g. `FOR UPDATE` |\n| String | Obtain a lock based on the SQL string e.g. `FOR UPDATE NOWAIT` |\n\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm requires_lock: true do\n    ...\n  end\n\n  ...\nend\n```\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm requires_lock: 'FOR UPDATE NOWAIT' do\n    ...\n  end\n\n  ...\nend\n```\n\n\n### Column name \u0026 migration\n\nAs a default AASM uses the column `aasm_state` to store the states. You can override\nthis by defining your favorite column name, using `:column` like this:\n\n```ruby\nclass Job \u003c ActiveRecord::Base\n  include AASM\n\n  aasm column: :my_state do\n    ...\n  end\n\n  aasm :another_state_machine, column: :second_state do\n    ...\n  end\nend\n```\n\nWhatever column name is used, make sure to add a migration to provide this column\n(of type `string`).\nDo not add default value for column at the database level. If you add default\nvalue in database then AASM callbacks on the initial state will not be fired upon\ninstantiation of the model.\n\n```ruby\nclass AddJobState \u003c ActiveRecord::Migration\n  def self.up\n    add_column :jobs, :aasm_state, :string\n  end\n\n  def self.down\n    remove_column :jobs, :aasm_state\n  end\nend\n```\n\n### Log State Changes\n\nLogging state change can be done using [paper_trail](https://github.com/paper-trail-gem/paper_trail) gem\n\nExample of implementation can be found here [https://github.com/nitsujri/aasm-papertrail-example](https://github.com/nitsujri/aasm-papertrail-example)\n\n\n### Inspection\n\nAASM supports query methods for states and events\n\nGiven the following `Job` class:\n\n```ruby\nclass Job\n  include AASM\n\n  aasm do\n    state :sleeping, initial: true\n    state :running, :cleaning\n\n    event :run do\n      transitions from: :sleeping, to: :running\n    end\n\n    event :clean do\n      transitions from: :running, to: :cleaning, guard: :cleaning_needed?\n    end\n\n    event :sleep do\n      transitions from: [:running, :cleaning], to: :sleeping\n    end\n  end\n\n  def cleaning_needed?\n    false\n  end\nend\n```\n\n```ruby\n# show all states\nJob.aasm.states.map(\u0026:name)\n#=\u003e [:sleeping, :running, :cleaning]\n\njob = Job.new\n\n# show all permitted states (from initial state)\njob.aasm.states(permitted: true).map(\u0026:name)\n#=\u003e [:running]\n\n# List all the permitted transitions(event and state pairs) from initial state\njob.aasm.permitted_transitions\n#=\u003e [{ :event =\u003e :run, :state =\u003e :running }]\n\njob.run\njob.aasm.states(permitted: true).map(\u0026:name)\n#=\u003e [:sleeping]\n\n# show all non permitted states\njob.aasm.states(permitted: false).map(\u0026:name)\n#=\u003e [:cleaning]\n\n# show all possible (triggerable) events from the current state\njob.aasm.events.map(\u0026:name)\n#=\u003e [:clean, :sleep]\n\n# show all permitted events\njob.aasm.events(permitted: true).map(\u0026:name)\n#=\u003e [:sleep]\n\n# show all non permitted events\njob.aasm.events(permitted: false).map(\u0026:name)\n#=\u003e [:clean]\n\n# show all possible events except a specific one\njob.aasm.events(reject: :sleep).map(\u0026:name)\n#=\u003e [:clean]\n\n# list states for select\nJob.aasm.states_for_select\n#=\u003e [[\"Sleeping\", \"sleeping\"], [\"Running\", \"running\"], [\"Cleaning\", \"cleaning\"]]\n\n# show permitted states with guard parameter\njob.aasm.states({permitted: true}, guard_parameter).map(\u0026:name)\n```\n\n\n### Warning output\n\nWarnings are by default printed to `STDERR`. If you want to log those warnings to another output,\nuse\n\n```ruby\nclass Job\n  include AASM\n\n  aasm logger: Rails.logger do\n    ...\n  end\nend\n```\n\nYou can hide warnings by setting `AASM::Configuration.hide_warnings = true`\n\n### RubyMotion support\n\nNow supports [CodeDataQuery](https://github.com/infinitered/cdq.git) !\nHowever I'm still in the process of submitting my compatibility updates to their repository.\nIn the meantime you can use [my fork](https://github.com/Infotaku/cdq.git), there may still be some minor issues but I intend to extensively use it myself, so fixes should come fast.\n\nWarnings:\n- Due to RubyMotion Proc's lack of 'source_location' method, it may be harder\nto find out the origin of a \"cannot transition from\" error. I would recommend using\nthe 'instance method symbol / string' way whenever possible when defining guardians and callbacks.\n\n\n### Testing\n\n#### RSpec\n\nAASM provides some matchers for [RSpec](http://rspec.info):\n* `transition_from`,\n* `have_state`, `allow_event`\n* and `allow_transition_to`.\n\n##### Installation Instructions:\n* Add `require 'aasm/rspec'` to your `spec_helper.rb` file.\n\n##### Examples Of Usage in Rspec:\n\n```ruby\n# classes with only the default state machine\njob = Job.new\nexpect(job).to transition_from(:sleeping).to(:running).on_event(:run)\nexpect(job).not_to transition_from(:sleeping).to(:cleaning).on_event(:run)\nexpect(job).to have_state(:sleeping)\nexpect(job).not_to have_state(:running)\nexpect(job).to allow_event :run\nexpect(job).to_not allow_event :clean\nexpect(job).to allow_transition_to(:running)\nexpect(job).to_not allow_transition_to(:cleaning)\n# on_event also accept multiple arguments\nexpect(job).to transition_from(:sleeping).to(:running).on_event(:run, :defragmentation)\n\n# classes with multiple state machine\nmultiple = SimpleMultipleExample.new\nexpect(multiple).to transition_from(:standing).to(:walking).on_event(:walk).on(:move)\nexpect(multiple).to_not transition_from(:standing).to(:running).on_event(:walk).on(:move)\nexpect(multiple).to have_state(:standing).on(:move)\nexpect(multiple).not_to have_state(:walking).on(:move)\nexpect(multiple).to allow_event(:walk).on(:move)\nexpect(multiple).to_not allow_event(:hold).on(:move)\nexpect(multiple).to allow_transition_to(:walking).on(:move)\nexpect(multiple).to_not allow_transition_to(:running).on(:move)\nexpect(multiple).to transition_from(:sleeping).to(:processing).on_event(:start).on(:work)\nexpect(multiple).to_not transition_from(:sleeping).to(:sleeping).on_event(:start).on(:work)\nexpect(multiple).to have_state(:sleeping).on(:work)\nexpect(multiple).not_to have_state(:processing).on(:work)\nexpect(multiple).to allow_event(:start).on(:move)\nexpect(multiple).to_not allow_event(:stop).on(:move)\nexpect(multiple).to allow_transition_to(:processing).on(:move)\nexpect(multiple).to_not allow_transition_to(:sleeping).on(:move)\n# allow_event also accepts arguments\nexpect(job).to allow_event(:run).with(:defragmentation)\n\n```\n\n#### Minitest\n\nAASM provides assertions and rspec-like expectations for [Minitest](https://github.com/seattlerb/minitest).\n\n##### Assertions\n\nList of supported assertions: `assert_have_state`, `refute_have_state`, `assert_transitions_from`, `refute_transitions_from`, `assert_event_allowed`, `refute_event_allowed`, `assert_transition_to_allowed`, `refute_transition_to_allowed`.\n\n\n##### Examples Of Usage (Minitest):\n\nAdd `require 'aasm/minitest'` to your `test_helper.rb` file and use them like this:\n\n```ruby\n# classes with only the default state machine\njob = Job.new\nassert_transitions_from job, :sleeping, to: :running, on_event: :run\nrefute_transitions_from job, :sleeping, to: :cleaning, on_event: :run\nassert_have_state job, :sleeping\nrefute_have_state job, :running\nassert_event_allowed job, :run\nrefute_event_allowed job, :clean\nassert_transition_to_allowed job, :running\nrefute_transition_to_allowed job, :cleaning\n# on_event also accept arguments\nassert_transitions_from job, :sleeping, :defragmentation, to: :running, on_event: :run\n\n# classes with multiple state machine\nmultiple = SimpleMultipleExample.new\nassert_transitions_from multiple, :standing, to: :walking, on_event: :walk, on: :move\nrefute_transitions_from multiple, :standing, to: :running, on_event: :walk, on: :move\nassert_have_state multiple, :standing, on: :move\nrefute_have_state multiple, :walking, on: :move\nassert_event_allowed multiple, :walk, on: :move\nrefute_event_allowed multiple, :hold, on: :move\nassert_transition_to_allowed multiple, :walking, on: :move\nrefute_transition_to_allowed multiple, :running, on: :move\nassert_transitions_from multiple, :sleeping, to: :processing, on_event: :start, on: :work\nrefute_transitions_from multiple, :sleeping, to: :sleeping, on_event: :start, on: :work\nassert_have_state multiple, :sleeping, on: :work\nrefute_have_state multiple, :processing, on: :work\nassert_event_allowed multiple, :start, on: :move\nrefute_event_allowed multiple, :stop, on: :move\nassert_transition_to_allowed multiple, :processing, on: :move\nrefute_transition_to_allowed multiple, :sleeping, on: :move\n```\n\n##### Expectations\n\nList of supported expectations: `must_transition_from`, `wont_transition_from`, `must_have_state`, `wont_have_state`, `must_allow_event`, `wont_allow_event`, `must_allow_transition_to`, `wont_allow_transition_to`.\n\nAdd `require 'aasm/minitest_spec'` to your `test_helper.rb` file and use them like this:\n\n```ruby\n# classes with only the default state machine\njob = Job.new\njob.must_transition_from :sleeping, to: :running, on_event: :run\njob.wont_transition_from :sleeping, to: :cleaning, on_event: :run\njob.must_have_state :sleeping\njob.wont_have_state :running\njob.must_allow_event :run\njob.wont_allow_event :clean\njob.must_allow_transition_to :running\njob.wont_allow_transition_to :cleaning\n# on_event also accept arguments\njob.must_transition_from :sleeping, :defragmentation, to: :running, on_event: :run\n\n# classes with multiple state machine\nmultiple = SimpleMultipleExample.new\nmultiple.must_transition_from :standing, to: :walking, on_event: :walk, on: :move\nmultiple.wont_transition_from :standing, to: :running, on_event: :walk, on: :move\nmultiple.must_have_state :standing, on: :move\nmultiple.wont_have_state :walking, on: :move\nmultiple.must_allow_event :walk, on: :move\nmultiple.wont_allow_event :hold, on: :move\nmultiple.must_allow_transition_to :walking, on: :move\nmultiple.wont_allow_transition_to :running, on: :move\nmultiple.must_transition_from :sleeping, to: :processing, on_event: :start, on: :work\nmultiple.wont_transition_from :sleeping, to: :sleeping, on_event: :start, on: :work\nmultiple.must_have_state :sleeping, on: :work\nmultiple.wont_have_state :processing, on: :work\nmultiple.must_allow_event :start, on: :move\nmultiple.wont_allow_event :stop, on: :move\nmultiple.must_allow_transition_to :processing, on: :move\nmultiple.wont_allow_transition_to :sleeping, on: :move\n```\n\n## \u003ca id=\"installation\"\u003eInstallation ##\n\n### Manually from RubyGems.org ###\n\n```sh\n% gem install aasm\n```\n\n### Or if you are using Bundler ###\n\n```ruby\n# Gemfile\ngem 'aasm'\n```\n\n### Building your own gems ###\n\n```sh\n% rake build\n% sudo gem install pkg/aasm-x.y.z.gem\n```\n\n### Generators\n\nAfter installing AASM you can run generator:\n\n```sh\n% rails generate aasm NAME [COLUMN_NAME]\n```\nReplace NAME with the Model name, COLUMN_NAME is optional(default is 'aasm_state').\nThis will create a model (if one does not exist) and configure it with aasm block.\nFor ActiveRecord orm a migration file is added to add aasm state column to table.\n\n### Docker\n\nRun test suite easily on docker\n```\n1. docker-compose build aasm\n2. docker-compose run --rm aasm\n```\n\n## Latest changes ##\n\nTake a look at the [CHANGELOG](https://github.com/aasm/aasm/blob/master/CHANGELOG.md) for details about recent changes to the current version.\n\n## Questions? ##\n\nFeel free to\n\n* [create an issue on GitHub](https://github.com/aasm/aasm/issues)\n* [ask a question on StackOverflow](http://stackoverflow.com) (tag with `aasm`)\n* send us a tweet [@aasm](http://twitter.com/aasm)\n\n## Maintainers ##\n\n* [Scott Barron](https://github.com/rubyist) (2006–2009, original author)\n* [Travis Tilley](https://github.com/ttilley) (2009–2011)\n* [Thorsten Böttger](http://github.com/alto) (since 2011)\n* [Anil Maurya](http://github.com/anilmaurya) (since 2016)\n\n\n\n## Stargazers over time\n\n[![Stargazers over time](https://starchart.cc/aasm/aasm.svg)](https://starchart.cc/aasm/aasm)\n\n\n## [Contributing](CONTRIBUTING.md)\n\n## Warranty ##\n\nThis software is provided \"as is\" and without any express or\nimplied warranties, including, without limitation, the implied\nwarranties of merchantibility and fitness for a particular\npurpose.\n\n## License ##\n\nCopyright (c) 2006-2017 Scott Barron\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\nOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":["Ruby","Active Record","Rails Plugins","State Machines","Web 后端","模型","Gems","WebSocket","ActiveRecord","Libraries"],"sub_categories":["Omniauth","State Machines","Ruby"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faasm%2Faasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faasm%2Faasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faasm%2Faasm/lists"}