{"id":13878761,"url":"https://github.com/infinum/enumerations","last_synced_at":"2026-03-04T19:32:27.928Z","repository":{"id":1572076,"uuid":"2011493","full_name":"infinum/enumerations","owner":"infinum","description":"Better Rails Enumerations","archived":false,"fork":false,"pushed_at":"2026-01-16T13:39:18.000Z","size":207,"stargazers_count":38,"open_issues_count":1,"forks_count":4,"subscribers_count":13,"default_branch":"master","last_synced_at":"2026-01-17T03:40:47.748Z","etag":null,"topics":["enumeration","gem","open-source","rails","ruby"],"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/infinum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2011-07-07T09:48:00.000Z","updated_at":"2026-01-16T13:37:12.000Z","dependencies_parsed_at":"2026-01-16T17:06:47.885Z","dependency_job_id":null,"html_url":"https://github.com/infinum/enumerations","commit_stats":{"total_commits":198,"total_committers":14,"mean_commits":"14.142857142857142","dds":0.5101010101010102,"last_synced_commit":"d7a8caae3746525f1c9123357259788c3f84bb56"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/infinum/enumerations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinum%2Fenumerations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinum%2Fenumerations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinum%2Fenumerations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinum%2Fenumerations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infinum","download_url":"https://codeload.github.com/infinum/enumerations/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinum%2Fenumerations/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29532421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T03:01:11.216Z","status":"ssl_error","status_checked_at":"2026-02-17T03:00:31.803Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["enumeration","gem","open-source","rails","ruby"],"created_at":"2024-08-06T08:01:59.109Z","updated_at":"2026-03-04T19:32:27.908Z","avatar_url":"https://github.com/infinum.png","language":"Ruby","readme":"Enumerations\n============\n\n[![Gem Version](https://badge.fury.io/rb/enumerations.svg)](https://badge.fury.io/rb/enumerations)\n[![Maintainability](https://api.codeclimate.com/v1/badges/c3b96c5afceaa9be2173/maintainability)](https://codeclimate.com/github/infinum/enumerations/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/c3b96c5afceaa9be2173/test_coverage)](https://codeclimate.com/github/infinum/enumerations/test_coverage)\n![Build Status](https://github.com/infinum/enumerations/actions/workflows/test.yml/badge.svg)\n\nRails plugin for Enumerations in ActiveRecord models.\n\nInstallation\n============\n\nInside your `Gemfile` add the following:\n\n```ruby\ngem 'enumerations'\n```\n\nUsage\n=====\n\n## Defining enumerations\n\nCreate a model for your enumerations:\n\n```ruby\nclass Status \u003c Enumerations::Base\n  values draft:           { name: 'Draft' },\n         review_pending:  { name: 'Review pending' },\n         published:       { name: 'Published' }\nend\n```\n\nOr you can use `value` method for defining your enumerations:\n\n```ruby\nclass Status \u003c Enumerations::Base\n  value :draft,           name: 'Draft'\n  value :review_pending,  name: 'Review pending'\n  value :published,       name: 'Published'\nend\n```\n\nInclude enumerations for integer fields in other models:\n\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :status\n\n  validates :status, presence: true\nend\n```\n\nYou can pass attributes to specify which enumeration and which column to use:\n\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :status,\n              foreign_key: :post_status,   # specifies which column to use\n              class_name: Post::Status     # specifies the class of the enumerator\n\n  validates :post_status, presence: true\nend\n```\nAttribute `foreign_key` you can pass as a `String` or a `Symbol`. Attribute `class_name` can be set as a `String`, a `Symbol` or a `String`.\n\n\n\n## Setting enumeration value to objects\n\nSet enumerations:\n\n```ruby\n@post = Post.first\n@post.status = Status.draft\n@post.save\n```\n\nOr you can set enumerations by `symbol`:\n\n```ruby\n@post.status = Status.find(:draft)\n```\n\n\u003e If you try to set value that is not an Enumeration value (except `nil`), you will get an `Enumerations::InvalidValueError` exception. You can turn this exception off in configuration.\n\nAlso, you can set enumeration value like this:\n\n```ruby\n@post.status_draft!\n```\n\n\u003e When you include enumerations into your model, you'll get methods for setting each enumeration value.\nEach method name is consists from enumeration name and enumeration value name with **!** at the end. Examples:\n\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :status\nend\n\n@post.status_draft!\n```\n\n```ruby\nclass User \u003c ActiveRecord::Base\n  enumeration :role\nend\n\n@user.role_admin!\n```\n\n```ruby\nclass User \u003c ActiveRecord::Base\n  enumeration :type, class_name: Role\nend\n\n@user.type_editor!\n```\n\n\n\n## Finder methods\n\nFind enumerations by `id`:\n\n```ruby\n@post.status = Status.find(2)                 # =\u003e Review pending\n@post.save\n```\n\nOther finding methods:\n\n```ruby\n# Find by key as a Symbol\nStatus.find(:review_pending)                  # =\u003e Review pending\n\n# Find by key as a String\nStatus.find('draft')                          # =\u003e Draft\n\n# Find by multiple attributes\nStatus.find_by(name: 'None', visible: true)   # =\u003e None\n```\n\nCompare enumerations:\n\n```ruby\n@post.status == :published                    # =\u003e true\n@post.status == 'published'                   # =\u003e true\n@post.status == Status.published              # =\u003e true\n@post.status.published?                       # =\u003e true\n```\n\nGet all enumerations:\n\n```ruby\nStatus.all\n```\n\n\n\n## Filtering methods\n\nEnumerations can be filtered with `where` method, similar to `ActiveRecord::QueryMethods#where`.\n\n```ruby\nRole.where(admin: true)                       # =\u003e [Role.admin, Role.editor]\nRole.where(admin: true, active: true)         # =\u003e [Role.admin]\n```\n\n\n\n## Scopes on model\n\nWith enumerations, you'll get scope for each enumeration value in the\nfollowing format:\n\n```ruby\nwith_#{enumeration_name}_#{enumeration_value_name}\nwithout_#{enumeration_name}_#{enumeration_value_name}\n```\n\nor you can use the following scope and pass an array of enumerations:\n\n```ruby\nwith_#{enumeration_name}(enumeration, ...)\nwithout_#{enumeration_name}(enumeration, ...)\n```\n\nExamples:\n\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :status\nend\n\nPost.with_status_draft                        # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.without_status_review_pending            # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_status(:draft)                      # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.without_status(:draft)                   # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_status(Status.draft)                # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_status(:draft, :review_pending)     # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_status(Status.draft, 'published')   # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_status([:draft, :review_pending])   # =\u003e \u003c#ActiveRecord::Relation []\u003e\n```\n\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :my_status, class_name: Status\nend\n\nPost.with_my_status_draft                      # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_my_status_review_pending             # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.with_my_status(:draft)                    # =\u003e \u003c#ActiveRecord::Relation []\u003e\nPost.without_my_status(:draft)                 # =\u003e \u003c#ActiveRecord::Relation []\u003e\n```\n\nEach scope returns all records with specified enumeration value.\n\n\n\n## Forms usage\n\nUse in forms:\n\n```ruby\n%p\n  = f.label :status\n  %br\n  = f.collection_select :status, Status.all, :symbol, :name\n```\n\n\n\n## Validating input\n\nEnumerations will by default raise an exception if you try to set an invalid value. This prevents usage of validations, which you might want to add if you're developing an API and have to return meaningful errors to API clients.\n\nYou can enable validations by first disabling error raising on invalid input (see [configuration](#configuration)). Then, you should add an inclusion validation to enumerated attributes:\n```ruby\nclass Post \u003c ActiveRecord::Base\n  enumeration :status\n\n  validates :status, inclusion: { in: Status.all }\nend\n```\n\nYou'll now get an appropriate error message when you insert an invalid value:\n```ruby\n\u003e post = Post.new(status: 'invalid')\n\u003e post.valid?\n=\u003e false\n\u003e post.errors.full_messages.to_sentence\n=\u003e \"Status is not included in the list\"\n\u003e post.status\n=\u003e \"invalid\"\n```\n\nAdvanced Usage\n=====\n\nExcept `name` you can specify any other attributes to your enumerations:\n\n```ruby\nclass Status \u003c Enumerations::Base\n  value :draft,           id: 1, name: 'Draft', published: false\n  value :review_pending,  id: 2, name: 'Review pending', description: 'Some description...'\n  value :published,       id: 3, name: 'Published', published: true\n  value :other                                 # passing no attributes is also allowed\nend\n```\n\nEvery enumeration has `id`, `name`, `description` and `published` methods.\nIf you call method that is not in attribute list for enumeration, it will return `nil`.\n\n```ruby\nStatus.review_pending.description              # =\u003e 'Some description...'\nStatus.draft.description                       # =\u003e nil\n```\n\nFor each attribute, you have predicate method. Predicate methods are actually calling `present?`\nmethod on attribute value:\n\n```ruby\nStatus.draft.name?                             # =\u003e true\nStatus.draft.published?                        # =\u003e false\nStatus.published.published?                    # =\u003e true\nStatus.other.name?                             # =\u003e false\n```\n\nTranslations\n=====\n\n**Enumerations** uses power of I18n API (if translate_attributes configuration is set to true) to enable you to create a locale file\nfor enumerations like this:\n\n```yaml\n---\nen:\n  enumerations:\n    status:\n      draft:\n        name: Draft\n        description: Article draft...\n        ...\n    role:\n      admin:\n        name: Administrator\n```\n\n\u003e You can separate enumerations locales into a separate `*.yml` files.\n\u003e Then you should add locale file paths to I18n load path:\n\n```ruby\n# config/initializers/locale.rb\n\n# Where the I18n library should search for translation files (e.g.):\nI18n.load_path += Dir[Rails.root.join('config', 'locales', 'enumerations', '*.yml')]\n```\n\nConfiguration\n=============\n\nBasically no configuration is needed.\n\n**Enumerations** has four configuration options.\nYou can customize primary key, foreign key suffix, whether to translate attributes and whether to raise `Enumerations::InvalidValueError` exception when setting invalid values.\nJust add initializer file to `config/initializers/enumerations.rb`.\n\nExample of configuration:\n\n```ruby\n# config/initializers/enumerations.rb\n\nEnumerations.configure do |config|\n  config.primary_key               = :id\n  config.foreign_key_suffix        = :id\n  config.translate_attributes      = true\n  config.raise_invalid_value_error = true\nend\n```\n\nBy default, `primary_key` and `foreign_key_suffix` are set to `nil`.\n\nBy default model enumeration value is saved to column with same name as enumeration.\nIf you set enumeration as:\n```ruby\nenumeration :status\n```\nthen model should have `status` column (as `String` type).\nIf you want save an `ID` to this column, you can set `foreign_key_suffix` to `id`.\nThen model should have `status_id` column.\n\nIf you set `primary_key` then you need provide this attribute for all enumerations values.\nAlso, value from `primary_key` attribute will be stored to model as enumeration value.\n\nFor example:\n\n```ruby\n# with default configuration\n\npost = Post.new\npost.status = Status.draft      # =\u003e post.status = 'draft'\n\n# with configured primary_key and foreign_key_suffix:\n\nEnumerations.configure do |config|\n  config.primary_key        = :id\n  config.foreign_key_suffix = :id\nend\n\nclass Status \u003c Enumerations::Base\n  value :draft,           id: 1, name: 'Draft'\n  value :review_pending,  id: 2, name: 'Review pending',\n  value :published,       id: 3, name: 'Published', published: true\nend\n\npost = Post.new\npost.status = Status.draft      # =\u003e post.status_id = 1\n```\n\nIf you want to configure primary key or foreign key suffix per enumeration class, you can use `primary_key=` and `foreign_key_suffix=` class method:\n\n```ruby\nclass Status \u003c Enumerations::Base\n  self.primary_key = :id\n  self.foreign_key_suffix = :id\n\n  value :draft,           id: 1, name: 'Draft'\n  value :review_pending,  id: 2, name: 'Review pending'\nend\n```\n\nDatabase Enumerations\n=====================\n\nBy default, enumeration values are saved to database as `String`.\nIf you want, you can define `Enum` type in database:\n\n```sql\nCREATE TYPE status AS ENUM ('draft', 'review_pending', 'published');\n```\n\nThen you'll have enumeration as type in database and you can use it in database migrations:\n\n```ruby\nadd_column :posts, :status, :status, index: true\n```\n\nWith configuration option `primary_key`, you can store any type you want (e.g. `Integer`).\n\nAlso, for performance reasons, you should add indices to enumeration column.\n\n[Here](https://www.postgresql.org/docs/9.1/static/datatype-enum.html) you can find more informations about ENUM types.\n\n\n\nContributing\n============\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\nCredits\n=======\n**Enumerations** is maintained and sponsored by [Infinum](https://infinum.co)\n\nCopyright © 2010 - 2018 Infinum Ltd.\n\nLicense\n=======\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinum%2Fenumerations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfinum%2Fenumerations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinum%2Fenumerations/lists"}