{"id":15512653,"url":"https://github.com/amatsuda/stateful_enum","last_synced_at":"2025-12-25T05:28:53.728Z","repository":{"id":45578384,"uuid":"53919902","full_name":"amatsuda/stateful_enum","owner":"amatsuda","description":"A very simple state machine plugin built on top of ActiveRecord::Enum","archived":false,"fork":false,"pushed_at":"2025-05-01T20:16:52.000Z","size":193,"stargazers_count":631,"open_issues_count":15,"forks_count":38,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-01T20:31:10.199Z","etag":null,"topics":["activerecord","enum","rails","statemachine"],"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/amatsuda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2016-03-15T06:17:46.000Z","updated_at":"2025-05-01T20:16:55.000Z","dependencies_parsed_at":"2025-04-10T19:41:43.361Z","dependency_job_id":"66eda2eb-5beb-4af1-a4aa-5542792d16e1","html_url":"https://github.com/amatsuda/stateful_enum","commit_stats":{"total_commits":228,"total_committers":12,"mean_commits":19.0,"dds":0.1578947368421053,"last_synced_commit":"7dc34e3e28748511ddc47329503b388353fa03af"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amatsuda%2Fstateful_enum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amatsuda%2Fstateful_enum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amatsuda%2Fstateful_enum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amatsuda%2Fstateful_enum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amatsuda","download_url":"https://codeload.github.com/amatsuda/stateful_enum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059520,"owners_count":22007771,"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":["activerecord","enum","rails","statemachine"],"created_at":"2024-10-02T09:53:46.227Z","updated_at":"2025-12-25T05:28:53.716Z","avatar_url":"https://github.com/amatsuda.png","language":"Ruby","funding_links":[],"categories":["Ruby","Libraries"],"sub_categories":["Ruby"],"readme":"# StatefulEnum [![Build Status](https://github.com/amatsuda/stateful_enum/actions/workflows/main.yml/badge.svg)](https://github.com/amatsuda/stateful_enum/actions)\n\nstateful_enum is a state machine gem built on top of ActiveRecord's built-in ActiveRecord::Enum.\n\n\n## Installation\n\nAdd this line to your Rails app's Gemfile:\n\n```ruby\ngem 'stateful_enum'\n```\n\nAnd bundle.\n\n\n## Motivation\n\n### You Ain't Gonna Need Abstraction\n\nstateful_enum depends on ActiveRecord. If you prefer a \"well-abstracted\" state machine library that supports multiple datastores, or Plain Old Ruby Objects (who needs that feature?), I'm sorry but this gem is not for you.\n\n### I Hate Saving States in a VARCHAR Column\n\nFrom a database design point of view, I prefer to save state data in an INTEGER column rather than saving the state name directly in a VARCHAR column.\n\n### :heart: ActiveRecord::Enum\n\nActiveRecord 4.1+ has a very simple and useful built-in Enum DSL that provides human-friendly API over integer values in DB.\n\n### Method Names Should be Verbs\n\nAR::Enum automatically defines Ruby methods per each label. However, Enum labels are in most cases adjectives or past participle, which often creates weird method names.\nWhat we really want to define as methods are the transition events between states, and not the states themselves.\n\n\n## Usage\n\nThe stateful_enum gem extends AR::Enum definition to take a block with a similar DSL to the [state_machine](https://github.com/pluginaweek/state_machine) gem.\n\nExample:\n```ruby\nclass Bug \u003c ApplicationRecord\n  enum :status, {unassigned: 0, assigned: 1, resolved: 2, closed: 3} do\n    event :assign do\n      transition :unassigned =\u003e :assigned\n    end\n\n    event :resolve do\n      before do\n        self.resolved_at = Time.zone.now\n      end\n\n      transition [:unassigned, :assigned] =\u003e :resolved\n    end\n\n    event :close do\n      after do\n        Notifier.notify \"Bug##{id} has been closed.\"\n      end\n\n      transition all - [:closed] =\u003e :closed\n    end\n  end\nend\n```\n\n### Defining the States\n\nJust call the AR::Enum's `enum` method.  The only difference from the original `enum` method is that our `enum` call takes a block.\nPlease see the full API documentation of [AR::Enum](http://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) for more information.\n\n### Defining the Events\n\nYou can declare events through `event` method inside of an `enum` block. Then stateful_enum defines the following methods per each event:\n\n**An instance method to fire the event**\n\n```ruby\n@bug.assign  # does nothing and returns false if a valid transition for the current state is not defined\n```\n\n**An instance method with `!` to fire the event**\n```ruby\n@bug.assign!  # raises if a valid transition for the current state is not defined\n```\n\n**A predicate method that returns if the event is fireable**\n```ruby\n@bug.can_assign?  # returns if the `assign` event can be called on this bug or not\n```\n\n**An instance method that returns the state name after an event**\n```ruby\n@bug.assign_transition  #=\u003e :assigned\n```\n\n### Defining the Transitions\n\nYou can define state transitions through `transition` method inside of an `event` block.\n\nThere are a few important details to note regarding this feature:\n\n* The `transition` method takes a Hash each key of which is state \"from\" transitions to the Hash value.\n* The \"from\" states and the \"to\" states should both be given in Symbols.\n* The \"from\" state can be multiple states, in which case the key can be given as an Array of states, as shown in the usage example.\n* The \"from\" state can be `all` that means all defined states.\n* The \"from\" state can be an exception of Array of states, in this case the key can be a subtraction of `all` with the state to be excluded, as shown in the usage example.\n\n### :if and :unless Condition\n\nThe `transition` method takes an `:if` or `:unless` option as a Proc.\n\nExample:\n```ruby\nevent :assign do\n  transition :unassigned =\u003e :assigned, if: -\u003e { !!assigned_to }\nend\n```\n\n### Event Hooks\n\nYou can define `before` and `after` event hooks inside of an `event` block.\n\nEvent methods accept arguments (both positional and keyword arguments) that are passed through to the callbacks:\n\n```ruby\nclass Bug \u003c ApplicationRecord\n  enum :status, {unassigned: 0, assigned: 1, resolved: 2, closed: 3} do\n    event :close do\n      before do |closed_by:, reason: nil|\n        self.closed_by = closed_by\n        self.close_reason = reason\n      end\n\n      after do |closed_by:, **|\n        Notifier.notify \"Bug##{id} was closed by #{closed_by.name}\"\n      end\n\n      transition all - [:closed] =\u003e :closed\n    end\n  end\nend\n\n@bug.close(closed_by: current_user, reason: 'Duplicate')\n```\n\n### Inspecting All Defined Events And Current Possible Events\n\nYou can get the list of defined events from the model class:\n\n```ruby\nBug.stateful_enum.events\n#=\u003e an Array of all defined StatefulEnum::Machine::Event objects\n```\n\nAnd you can get the list of possible event definitions from the model instance:\n\n```ruby\nBug.new(status: :assigned).stateful_enum.possible_events\n#=\u003e an Array of StatefulEnum::Machine::Event objects that are callable from the receiver object\n```\n\nMaybe what you really need for your app is the list of possible event \"names\":\n\n```ruby\nBug.new(status: :assigned).stateful_enum.possible_event_names\n#=\u003e [:resolve, :close]\n```\n\nYou can get the list of next possible state names as well:\n\n```ruby\nBug.new(status: :assigned).stateful_enum.possible_states\n#=\u003e [:resolved, :closed]\n```\n\nThese features would help some kind of metaprogramming over state transitions.\n\n\n## Generating State Machine Diagrams\n\nstateful_enum includes a Rails generator that generates a state machine diagram.\nNote that you need to bundle the ruby-graphviz gem (and its dependencies) for the development env in order to run the generator.\n\n```bash\n% rails g stateful_enum:graph bug\n```\n\nYou can specify relative or absolute output path via environment variable `DEST_DIR`.\n\n```bash\n% DEST_DIR=doc rails g stateful_enum:graph bug\n```\n\n## TODO\n\n* Better Error handling\n\n\n## Supported Rails Versions\n\n* Rails 4.1.x, 4.2.x, 5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1, 7.2, 8.0, 8.1, and 8.2 (edge)\n\n\n## Contributing\n\nPull requests are welcome on GitHub at https://github.com/amatsuda/stateful_enum.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famatsuda%2Fstateful_enum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famatsuda%2Fstateful_enum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famatsuda%2Fstateful_enum/lists"}