enum_fields 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ae632efc222874e0efa5a5859e9e8b69b3a86e18ff162ea0d6b1ba2a65771da
+  data.tar.gz: 2dbbaffc02090af1a2a6185b966ec45e010defd99469d952ccecc3f9929cdc60
+SHA512:
+  metadata.gz: 7bd2c106cabd6e3709e9c69fc83535596818c5805359b63d34edd48515c8f31aaf33ed7033910470850966f66627ca2d1ee6e81859fc0efd9b7c0df190aa0d7f
+  data.tar.gz: 02ec904e369f37cdcdb6249a8a58370d02420188f8505f8abce43f967b23ab6dafc70870575eaf5603f85e04bb6b7bef19fe9df18700eda20fa2ef1ce4f94b52

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.0.1] - 2025-11-17
+
+### Added
+
+- Initial release of EnumFields gem
+- Support for enum-like fields with metadata properties
+- Array and Hash definition formats
+- Automatic generation of:
+  - Class methods (`<accessor>s`, `<accessor>s_count`, `<accessor>_values`, `<accessor>_options`)
+  - Instance getter/setter methods (when accessor differs from column)
+  - Metadata accessor methods (`<accessor>_metadata`)
+  - Property accessor methods for all defined properties (`<accessor>_<property>`)
+  - Inquiry methods (`<key>_<accessor>?`)
+  - Scopes (`<key>_<accessor>`)
+  - Validations (inclusion with `allow_nil: true`)
+- Custom column mapping support via `column:` option
+- Dynamic property method generation for custom properties
+
+[0.0.1]: https://github.com/kinnell/enum_fields/releases/tag/v0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kinnell Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# EnumFields
+
+Enhanced enum-like fields for ActiveRecord models with metadata support
+
+## Requirements
+
+- Ruby >= 2.7.6
+- Rails >= 6.0 (ActiveRecord and ActiveSupport)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'enum_fields'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Setup
+
+Include the `EnumFields` module in your `ApplicationRecord`:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include EnumFields
+
+  self.abstract_class = true
+end
+```
+
+Now all models inheriting from `ApplicationRecord` can use `enum_field`.
+
+### Defining Enum Fields
+
+#### Hash Definition (Recommended)
+
+```ruby
+class Campaign < ApplicationRecord
+  enum_field :stage, {
+    pending: {
+      value: 'pending',
+      label: 'Pending',
+      icon: 'clock',
+      color: 'yellow',
+      tooltip: 'Campaign is awaiting processing',
+    },
+    processing: {
+      value: 'processing',
+      label: 'Processing',
+      icon: 'cog',
+      color: 'blue',
+      tooltip: 'Campaign is being processed',
+    },
+    shipped: {
+      value: 'shipped',
+      label: 'Shipped',
+      icon: 'truck',
+      color: 'green',
+      tooltip: 'Campaign has been shipped',
+    },
+    delivered: {
+      value: 'delivered',
+      label: 'Delivered',
+      icon: 'check',
+      color: 'green',
+      tooltip: 'Campaign has been delivered',
+    },
+  }
+end
+```
+
+#### Array Definition (Simple)
+
+```ruby
+class Task < ApplicationRecord
+  enum_field :priority, ['low', 'medium', 'high']
+end
+```
+
+This automatically generates:
+
+```ruby
+{
+  low: {
+    value: 'low',
+    label: 'low',
+  },
+  medium: {
+    value: 'medium',
+    label: 'medium',
+  },
+  high: {
+    value: 'high',
+    label: 'high',
+  },
+}
+```
+
+#### Custom Column Mapping
+
+If your accessor name differs from your column name:
+
+```ruby
+class User < ApplicationRecord
+  enum_field :role, definitions, column: :user_role
+end
+```
+
+### Generated Methods
+
+For an enum field defined as:
+
+```ruby
+class Campaign < ApplicationRecord
+  enum_field :stage, {
+    draft: {
+      value: 'draft',
+      label: 'Draft',
+      icon: 'file',
+      color: 'gray',
+    },
+    scheduled: {
+      value: 'scheduled',
+      label: 'Scheduled',
+      icon: 'calendar',
+      color: 'blue',
+    },
+    completed: {
+      value: 'completed',
+      label: 'Completed',
+      icon: 'check',
+      color: 'green',
+    },
+  }
+end
+```
+
+#### Class Methods
+
+```ruby
+# Returns the definitions as an HashWithIndifferentAccess
+Campaign.stages
+
+# Returns the count of definitions
+Campaign.stages_count # 3
+
+# Returns the values of the definitions
+Campaign.stages_values # ['draft', 'scheduled', 'completed']
+
+# Returns the options for form helpers
+Campaign.stages_options # [['Draft', 'draft'], ['Scheduled', 'scheduled'], ['Completed', 'completed']]
+```
+
+#### Instance Getter/Setter
+
+If the accessor name differs from the column name, getter and setter methods are defined for the accessor.
+
+```ruby
+campaign.stage # 'draft'
+campaign.stage = 'scheduled'
+campaign.stage # 'scheduled'
+```
+
+- `campaign.stage` - Get the current stage value
+- `campaign.stage = 'scheduled'` - Set the stage value
+
+#### Metadata Methods
+
+The gem automatically creates accessor methods for all properties defined in your enum definitions.
+
+- `value` (required) - The actual value stored in the database
+- `label` (auto-generated if not provided) - A human-readable label
+
+Any additional properties you define (like `icon`, `color`, `tooltip`, etc.) will also get dedicated accessor methods automatically.
+
+```ruby
+# Returns the full metadata hash for current value
+campaign.stage_metadata
+# => { value: 'draft', label: 'Draft', icon: 'file', color: 'gray' }
+
+# Access individual properties
+campaign.stage_value # 'draft'
+campaign.stage_label # 'Draft'
+campaign.stage_icon  # 'file'
+campaign.stage_color # 'gray'
+```
+
+#### Inquiry Methods
+
+```ruby
+# Returns true if the current value is 'draft'
+campaign.draft_stage?
+
+# Returns true if the current value is 'scheduled'
+campaign.scheduled_stage?
+
+# Returns true if the current value is 'completed'
+campaign.completed_stage?
+```
+
+#### Scopes
+
+```ruby
+# Returns all campaigns with draft stage
+Campaign.draft_stage
+
+# Returns all campaigns with scheduled stage
+Campaign.scheduled_stage
+
+# Returns all campaigns with completed stage
+Campaign.completed_stage
+```
+
+#### Validation
+
+Automatically validates that the column value is included in the defined values (with `allow_nil: true`).
+
+### Custom Properties
+
+You can add any custom properties to your definitions, and the gem will automatically create accessor methods for them:
+
+```ruby
+class Ticket < ApplicationRecord
+  enum_field :priority, {
+    low: {
+      value: 'low',
+      label: 'Low Priority',
+      sla_hours: 72,
+      notify_manager: false,
+    },
+    high: {
+      value: 'high',
+      label: 'High Priority',
+      sla_hours: 4,
+      notify_manager: true,
+    },
+  }
+end
+
+# Access custom properties directly via generated methods
+ticket.priority_sla_hours      # 72
+ticket.priority_notify_manager # false
+
+# Or access via metadata hash
+ticket.priority_metadata[:sla_hours]      # 72
+ticket.priority_metadata[:notify_manager] # false
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kinnell/enum_fields.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/enum_fields/definition.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EnumFields
+  class Definition < SimpleDelegator
+    STANDARD_PROPERTIES = %i[
+      value
+      label
+    ].freeze
+
+    attr_reader :properties
+
+    def initialize(data)
+      @data = build(data)
+      raise InvalidDefinitionsError, 'Definitions must be a Hash or Array' unless valid_hash?(@data)
+
+      @properties = Set.new(STANDARD_PROPERTIES)
+      @properties.merge(@data.flat_map { |_, metadata| metadata.keys })
+
+      super(@data)
+    end
+
+    def data
+      __getobj__
+    end
+
+    def valid?
+      valid_hash?(__getobj__)
+    end
+
+    private
+
+    def build(input)
+      output = begin
+        case input
+        when HashWithIndifferentAccess
+          input
+        when Hash
+          input.with_indifferent_access
+        when Array
+          input.to_h do |value|
+            [value, { value: value }]
+          end.with_indifferent_access
+        else
+          raise InvalidDefinitionsError, "Invalid definitions format: #{input.class}"
+        end
+      end
+
+      output.transform_values do |metadata|
+        if metadata.key?(:label)
+          metadata
+        else
+          metadata.merge(label: metadata[:value])
+        end
+      end
+    end
+
+    def valid_hash?(data)
+      return false unless data.is_a?(HashWithIndifferentAccess)
+      return false unless data.values.all? { |metadata| metadata.key?(:value) }
+
+      true
+    end
+  end
+end

data/lib/enum_fields/enum_field.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module EnumFields
+  class EnumField
+    def self.define(**args)
+      new(**args).define!
+    end
+
+    def initialize(model_class:, accessor:, definition:, options: {})
+      @model_class = model_class
+      @accessor = accessor.to_sym
+      @column_name = options.fetch(:column, @accessor).to_sym
+      @definition = Definition.new(definition)
+    end
+
+    def define!
+      store_definition!
+      define_class_methods!
+      define_instance_getter!
+      define_instance_setter!
+      define_metadata_method!
+      define_property_methods!
+      define_inquiry_methods!
+      define_scopes!
+      define_validation!
+    end
+
+    private
+
+    def store_definition!
+      @model_class.enum_fields[@accessor] = @definition.data
+    end
+
+    def define_class_methods!
+      collection_name = @accessor.to_s.pluralize
+      definition_data = @definition.data
+
+      @model_class.define_singleton_method(collection_name) do
+        definition_data
+      end
+
+      @model_class.define_singleton_method("#{collection_name}_count") do
+        definition_data.size
+      end
+
+      @model_class.define_singleton_method("#{@accessor}_values") do
+        definition_data.values.pluck(:value)
+      end
+
+      @model_class.define_singleton_method("#{@accessor}_options") do
+        definition_data.map do |key, metadata|
+          [metadata[:label], key.to_s]
+        end
+      end
+    end
+
+    def define_instance_getter!
+      return if @accessor == @column_name
+
+      accessor = @accessor
+      column_name = @column_name
+
+      @model_class.define_method(accessor) do
+        attributes[column_name.to_s]
+      end
+    end
+
+    def define_instance_setter!
+      return if @accessor == @column_name
+
+      accessor = @accessor
+      column_name = @column_name
+
+      @model_class.define_method("#{accessor}=") do |value|
+        public_send("#{column_name}=", value)
+      end
+    end
+
+    def define_metadata_method!
+      accessor = @accessor
+      column_name = @column_name
+
+      @model_class.define_method("#{accessor}_metadata") do
+        column_value = attributes[column_name.to_s]
+        return nil if column_value.nil?
+
+        definitions = self.class.enum_field_for(accessor)
+        return nil if definitions.blank?
+
+        definitions[column_value]
+      end
+    end
+
+    def define_property_methods!
+      accessor = @accessor
+      column_name = @column_name
+
+      @definition.properties.each do |property|
+        @model_class.define_method("#{accessor}_#{property}") do
+          column_value = attributes[column_name.to_s]
+          return nil if column_value.nil?
+
+          definitions = self.class.enum_field_for(accessor)
+          return nil if definitions.blank?
+
+          definitions.dig(column_value, property)
+        end
+      end
+    end
+
+    def define_inquiry_methods!
+      accessor = @accessor
+      column_name = @column_name
+
+      @definition.each do |key, metadata|
+        definition_value = metadata[:value]
+        @model_class.define_method("#{key}_#{accessor}?") do
+          public_send(column_name) == definition_value
+        end
+      end
+    end
+
+    def define_scopes!
+      column_name = @column_name
+
+      @definition.each do |key, metadata|
+        definition_value = metadata[:value]
+        @model_class.scope("#{key}_#{@accessor}", -> { where(column_name => definition_value) })
+      end
+    end
+
+    def define_validation!
+      return if @definition.blank?
+
+      valid_values = @definition.values.pluck(:value)
+      @model_class.validates(@column_name, inclusion: {
+        in: valid_values,
+        allow_nil: true,
+      })
+    end
+  end
+end

data/lib/enum_fields/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module EnumFields
+  class MissingDefinitionsError < StandardError; end
+  class InvalidDefinitionsError < StandardError; end
+end

data/lib/enum_fields/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EnumFields
+  VERSION = '0.0.1'
+end

data/lib/enum_fields.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'active_support/concern'
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/inflector'
+require 'active_record'
+
+require_relative 'enum_fields/errors'
+require_relative 'enum_fields/version'
+
+module EnumFields
+  extend ActiveSupport::Concern
+  extend ActiveSupport::Autoload
+
+  autoload :Definition
+  autoload :EnumField
+
+  class_methods do
+    def enum_field(accessor, definition, options = {})
+      raise MissingDefinitionsError unless definition.present?
+
+      EnumField.define(
+        model_class: self,
+        accessor: accessor,
+        definition: definition,
+        options: options
+      )
+    end
+
+    def enum_field_for(accessor)
+      enum_fields[accessor]
+    end
+
+    def enum_fields
+      @enum_fields ||= {}.with_indifferent_access
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: enum_fields
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kinnell Shah
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: 'A Rails gem that provides enum-like functionality with support for metadata
+  properties (label, icon, color, tooltip) and automatic scopes, validations, and
+  inquiry methods.
+
+  '
+email:
+- kinnell@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/enum_fields.rb
+- lib/enum_fields/definition.rb
+- lib/enum_fields/enum_field.rb
+- lib/enum_fields/errors.rb
+- lib/enum_fields/version.rb
+homepage: https://github.com/kinnell/enum_fields
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kinnell/enum_fields
+  github_repo: ssh://github.com/kinnell/enum_fields
+  source_code_uri: https://github.com/kinnell/enum_fields
+  changelog_uri: https://github.com/kinnell/enum_fields/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kinnell/enum_fields/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Enhanced enum-like fields for ActiveRecord models with metadata support
+test_files: []