swifter_enum 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70feef4d3937618d057d99d62e1f08cc3a733580c523f9e131508d2386d1a1e
-  data.tar.gz: d47f2661ab4bf284eb13b7c40c358a226c6a6c5fc416567498fa312a4abc7960
+  metadata.gz: 256304e01311b60f1cf26bc7ad5d52fb7ba625bbc6c3b4216e6af129042d3516
+  data.tar.gz: fd82b318f1aa43a43c87eeebb965a36515b40f23f1a4a92928ed7d2e374052d5
 SHA512:
-  metadata.gz: c522bc3565a9e6d98da82f8e4e61b59e1e00632348600ab0d1550dd56760e4b1bc76a9e2e3c1a5a4de8f93131f81e051e239aa0d74327f46c65c99fe0f4eb40b
-  data.tar.gz: 2d3e496779b2c8ad21d393286279de27353c7c04f71f749ab8f15c371e270f936c08e5e108d79c564798eba640f2f5bf2bfedfd6076ee1d88acc3ba7b6b9187f
+  metadata.gz: 3e22b72fbbdc5a9090bc18189ea10542c08ad17fc4236067c304274c8bd5100090adf7e2eb5f94b264f5f9f1fe8b84a64c9e9bff849a24249b60d689ab53b443
+  data.tar.gz: 67cfb099c8c99eb3d754802841f49a144f6fcfba54cd2855dd6b3f645b0f16946870fe9f0bc1509f5ba06cedffbb92460755bf35a629156b10414a0fd3be6a21

data/CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Testing
+- Run all tests: `bundle exec appraisal rake test`
+- Run specific test file: `bundle exec appraisal rake test TEST=test/path/to/test_file.rb`
+- Test with specific Rails version: `bundle exec appraisal rails-7.1 rake test`
+
+### Code Quality
+- Run Standard Ruby linter: `standardrb`
+- Auto-fix linting issues: `standardrb --fix`
+
+### Building & Publishing
+- Build gem: `rake build`
+- Release new version: `rake release:publish` (builds, tags, and publishes to RubyGems)
+
+## Architecture
+
+SwifterEnum is a Ruby gem that extends Rails ActiveRecord enums by using classes instead of simple string/integer values. This allows encapsulating enum-related logic within the enum class itself.
+
+### Core Components
+
+1. **SwifterEnum::Base** (`lib/swifter_enum/base.rb`): Base class for all enum implementations. Key methods:
+   - `set_values`: Defines enum values (accepts hash of symbol->integer or array of symbols/strings)
+   - Instance comparison via `==` supports symbols, strings, and other enum instances
+   - `t` method for i18n translations
+   - `in?` method for collection checking
+
+2. **SwifterEnum Module** (`lib/swifter_enum/swifter_enum.rb`): ActiveSupport::Concern that adds `swifter_enum` class method to ActiveRecord models. Creates:
+   - Getter returning enum class instance
+   - Setter accepting enum instances or raw values
+   - `_raw` getter/setter for backward compatibility with standard Rails enums
+   - `_raws` class method returning the value mappings
+
+3. **SwifterEnumValidator** (`lib/swifter_enum/swifter_enum_validator.rb`): Custom validator for enum attributes
+
+4. **Generator** (`lib/swifter_enum/generators/enum/enum_generator.rb`): Rails generator for creating new enum classes in `app/models/swifter_enum/`
+
+### Integration Pattern
+
+Models use `swifter_enum :attribute_name, EnumClass` instead of standard Rails `enum`. This maintains database compatibility while returning enum class instances that can have custom methods.
+
+The gem maintains full backward compatibility through `_raw` accessors, making it easy to migrate existing Rails enums incrementally.

data/README.md

@@ -1,103 +1,283 @@
 # SwifterEnum
 
-SwifterEnum is a Ruby gem for creating enumerated types (enums) in Ruby on Rails applications. 
-
-It is inspired by Swift's enums, and allows you to keep logic related to your enum directly in your enum class.
-
-so - after defining
-
-    class Video < ApplicationRecord
-      swifter_enum :camera, CameraEnum
+SwifterEnum brings Swift-style enums to Ruby on Rails, allowing you to encapsulate behavior within your enum types rather than scattering it throughout your application.
+
+## Why SwifterEnum?
+
+In Swift, enums are first-class types that can have methods, computed properties, and associated values. SwifterEnum brings this powerful pattern to Rails by replacing simple string/integer enums with proper objects that can carry their own behavior.
+
+### Key Benefits
+
+**1. Encapsulated Behavior** - Your enum knows how to handle itself:
+
+```ruby
+# Define your enum with its behavior
+class PaymentStatusEnum < SwifterEnum::Base
+  set_values ({
+    pending: 0,
+    processing: 10,
+    completed: 20,
+    failed: 30,
+    refunded: 40
+  })
+
+  def completed?
+    [:completed, :refunded].include?(value)
+  end
+
+  def can_refund?
+    value == :completed
+  end
+
+  def icon
+    case value
+    when :pending then "clock"
+    when :processing then "spinner"
+    when :completed then "check-circle"
+    when :failed then "x-circle"
+    when :refunded then "rotate-left"
     end
+  end
+
+  def color
+    case value
+    when :pending then "gray"
+    when :processing then "blue"
+    when :completed then "green"
+    when :failed then "red"
+    when :refunded then "orange"
+    end
+  end
+end
+
+# Use it naturally in your models
+order.payment_status.completed?       # => true
+order.payment_status.can_refund?      # => true
+order.payment_status.icon             # => "check-circle"
+order.payment_status.color            # => "green"
+```
+
+**2. Type Safety** - Catch invalid values at runtime:
+
+```ruby
+# Safe access with bracket notation - raises error for invalid values
+status = PaymentStatusEnum[:completed]  # ✓ Returns enum instance
+status = PaymentStatusEnum[:invalid]    # ✗ Raises ArgumentError
+
+# Validation in models
+class Order < ApplicationRecord
+  swifter_enum :payment_status, PaymentStatusEnum
+  validates :payment_status, swifter_enum: true
+end
+```
+
+**3. Smart Enum Objects with Flexible Equality** - Returns enum instances that work naturally with symbols and strings:
+
+```ruby
+order.payment_status  # => #<PaymentStatusEnum @value=:completed>
+
+# Flexible equality checking - all of these work:
+order.payment_status == :completed           # => true (symbol comparison)
+order.payment_status == "completed"          # => true (string comparison)
+order.payment_status == other.payment_status # => true (enum instance comparison)
+
+# Use in case statements naturally
+case order.payment_status
+when :pending    then "Waiting for payment"
+when :completed  then "All done!"
+when :failed     then "Something went wrong"
+end
+
+# Or in arrays
+[:completed, :refunded].include?(order.payment_status)  # => true
+```
+
+**4. Seamless Rails Integration** - All standard Rails enum features continue to work:
+
+```ruby
+# Familiar Rails enum syntax
+class Order < ApplicationRecord
+  swifter_enum :payment_status, PaymentStatusEnum
+  swifter_enum :priority, PriorityEnum
+end
+
+# Standard Rails enum features work unchanged:
+order.payment_status = :processing        # Set with symbol, string, or enum instance
+order.payment_status = "processing"       # String works too
+order.payment_status = PaymentStatusEnum[:processing]  # Or enum instance
+order.completed!                          # Bang method sets and saves
+order.completed?                          # => true (query method)
+order.not_completed?                      # => false (negative query)
+
+Order.completed                           # Scope returning all completed orders
+Order.not_completed                       # Scope returning all non-completed orders
+```
+
+**5. Progressive Migration** - Adopt incrementally without breaking existing code:
+
+```ruby
+order.payment_status      # => #<PaymentStatusEnum @value=:completed>
+
+# Both setters work
+order.payment_status = :pending           # Symbol
+order.payment_status = PaymentStatusEnum[:pending]  # Enum instance
+
+# Raw methods provide an 'escape hatch' to standard Rails enum handling
+order.payment_status_raw  # => "completed" (original Rails enum value)
+Order.payment_status_raws  # => {"pending"=>0, "processing"=>10, ...}
+```
+
+## Real-World Example
+
+Consider a subscription system where enum behavior naturally belongs with the enum itself:
+
+```ruby
+class SubscriptionTierEnum < SwifterEnum::Base
+  set_values ({
+    free: 0,
+    basic: 10,
+    pro: 20,
+    enterprise: 30
+  })
+
+  def price
+    case value
+    when :free then 0
+    when :basic then 9.99
+    when :pro then 29.99
+    when :enterprise then 99.99
+    end
+  end
+
+  def features
+    case value
+    when :free then ["5 projects", "Basic support"]
+    when :basic then ["20 projects", "Email support", "API access"]
+    when :pro then ["Unlimited projects", "Priority support", "Advanced API"]
+    when :enterprise then ["Everything in Pro", "SSO", "Dedicated support", "SLA"]
+    end
+  end
+
+  def can_upgrade_to?(other_tier)
+    return false unless other_tier.is_a?(self.class)
+    self.class.values[other_tier.value] > self.class.values[value]
+  end
+
+  def badge_color
+    case value
+    when :free then "gray"
+    when :basic then "blue"
+    when :pro then "purple"
+    when :enterprise then "gold"
+    end
+  end
+end
 
-you can then define and access methods on your enum like
+# Clean, expressive code in your views and controllers
+current_user.subscription_tier.price           # => 29.99
+current_user.subscription_tier.features        # => ["Unlimited projects", ...]
+current_user.subscription_tier.can_upgrade_to?(SubscriptionTierEnum[:enterprise])  # => true
 
-`video.camera.icon`
+# In your views
+<span class="badge badge-<%= current_user.subscription_tier.badge_color %>">
+  <%= current_user.subscription_tier.t %>
+</span>
+<ul>
+  <% current_user.subscription_tier.features.each do |feature| %>
+    <li><%= feature %></li>
+  <% end %>
+</ul>
+```
 
-This avoids helper methods which distribute your enum logic around your application.
+This approach eliminates helper methods, reduces case statements scattered across your codebase, and keeps related logic together where it belongs.
 
-**Before**
 
-helper method somewhere in the app
+## Installation
 
-    #app/helpers/controller_helper.rb
+Add this line to your application's Gemfile:
 
-    def icon_for(camera:)
-      ...
-    end
+    gem 'swifter_enum'
 
-called with
+## Usage
 
-    icon_for(camera:my_model.camera)
+### Basic Setup
 
-**After**
+Define your enum class inheriting from `SwifterEnum::Base`:
 
-logic encapsluated within the enum class
+```ruby
+class CameraEnum < SwifterEnum::Base
+  # Using integers for database storage (most common)
+  set_values ({ videographer: 0, handcam: 1 })
 
-    #app/models/swifter_enum/camera_enum.rb
-    class CameraEnum < SwifterEnum::Base
-      set_values ({ videographer: 0, handcam: 1 })
+  # Or use strings for database storage (see "Using string values to store Enum" section)
+  # set_values [:videographer, :handcam]
 
-      def icon
-        ...
-      end
+  def icon
+    case @value
+    when :videographer then "icons/video-camera"
+    when :handcam then "icons/hand-stop"
     end
+  end
+end
+```
 
-called with
-
-    my_model.camera.icon
-
-I was prompted to create this gem by reading about enum approaches in [the RailsNotes Newsletter](https://railsnotes.beehiiv.com/p/issue-17-enums-value-objects-field-guide-enum-sort-in-order-of). Like any good programmer, none of those solutions *quite* met my requirements. Hopefully it will be useful. I welcome feedback, fixes and pull requests.
+Use it in your model:
 
+```ruby
+class Video < ApplicationRecord
+  swifter_enum :camera, CameraEnum
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'swifter_enum'
+  # Optional validation
+  validates :camera, swifter_enum: true
+end
+```
 
-## Usage
+### Working with Enum Values
 
-### Overview
+```ruby
+video = Video.first
 
+# Getter returns an enum instance (not a string/symbol)
+video.camera                    # => #<CameraEnum:0x000... @value=:handcam>
+video.camera.value              # => :handcam (access underlying symbol)
 
-SwifterEnums act like a normal Rails enum - except that instead of returning string values, they return an instance of your selected class.
+# Multiple ways to set values
+video.camera = :videographer                    # Symbol
+video.camera = "videographer"                   # String
+video.camera = CameraEnum[:videographer]        # Enum instance
+video.camera = other_video.camera              # Copy from another instance
 
-They also have various affordances so that in many cases, you can treat them as if they return symbol values.
+# Call your custom methods
+video.camera.icon               # => "icons/video-camera"
 
-We have a Video ActiveModel with an enum defined by
+# Works naturally with conditionals
+if video.camera == :handcam
+  # Do something
+end
+```
 
-    class Video < ApplicationRecord
-      swifter_enum :camera, CameraEnum
-    end
+### Safe Value Access with Bracket Notation
 
-CameraEnum is a class like the following
+You can use bracket notation to safely access enum values, which will raise an error if you try to access a non-existent value:
 
-    class CameraEnum < SwifterEnum::Base
-      set_values ({ videographer: 0, handcam: 1 })
+    # Access enum values with bracket notation
+    emotion = EmotionEnum[:happy]
+    emotion => #<EmotionEnum:0x0000000134c7c290 @value=:happy>
 
-      def icon
-        case @value
-        when :videographer
-          "icons/video-camera"
-        when :handcam
-          "icons/hand-stop"
-        end
-      end
-    end
+    # Raises ArgumentError for invalid values
+    EmotionEnum[:invalid]  # ArgumentError: Unknown enum value: :invalid
 
-This provides a richer approach to enums:
+    # Must use symbols, not strings
+    EmotionEnum["happy"]   # ArgumentError: Enum key must be a Symbol, got String
 
-    v = Video.first
-    v.camera => #<CameraEnum:0x0000000134c7c290 @value=:handcam> 
-    v.camera.value => :handcam 
+This is useful when you want to ensure you're only using valid enum values, such as when processing user input or configuration:
 
-    #you can set values directly
-    v.camera = :videographer
-    v.camera => #<CameraEnum:0x000000013385f078 @value=:videographer> 
+    # Example: Setting a model attribute with validation
+    video.camera = CameraEnum[:videographer]  # Safe - will raise if :videographer doesn't exist
 
-    #the purpose of this gem is that you can now define and access methods on the CameraEnum
-    v.camera.icon => "icons/video-camera" 
+    # Example: Using with dynamic values
+    status_key = params[:status].to_sym
+    model.status = StatusEnum[status_key]  # Will raise error if status_key is invalid
 
 
 ### Using Enums in ActiveRecord Models

data/gemfiles/rails_7.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    swifter_enum (0.9.7)
+    swifter_enum (1.0.0)
       activemodel (>= 7.0, < 9.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    swifter_enum (0.9.7)
+    swifter_enum (1.0.0)
       activemodel (>= 7.0, < 9.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)

data/lib/swifter_enum/base.rb

@@ -19,6 +19,18 @@ module SwifterEnum
         @values.keys.map { |key| new(key) }
       end
 
+      def [](key)
+        unless key.is_a?(Symbol)
+          raise ArgumentError, "Enum key must be a Symbol, got #{key.class}"
+        end
+
+        unless @values.key?(key)
+          raise ArgumentError, "Unknown enum value: :#{key}. Valid values are: #{@values.keys.map { |k| ":#{k}" }.join(", ")}"
+        end
+
+        new(key)
+      end
+
       private
 
       def validate_array_elements!(array)

data/lib/swifter_enum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwifterEnum
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swifter_enum
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Rob Jonson
@@ -125,10 +125,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
-description: Simple enum for active record that takes inspiration from Swift's enums
-  to allow you to encapsulate enum logic within an enum class. This is easy to drop-in
-  as a replacement for regular rails enums, with minimal changes required. Once you
-  switch, then you can easily extend your enums with methods.
+description: 'SwifterEnum transforms Rails enums from simple values into powerful
+  objects with methods, computed properties, and type safety. Your enums become smart:
+  payment_status.can_refund?, subscription.price, status.icon - all while maintaining
+  100% Rails enum compatibility. Drop-in replacement that eliminates scattered helper
+  methods and case statements throughout your codebase.'
 email:
 - rob@hobbyistsoftware.com
 executables: []
@@ -138,6 +139,7 @@ files:
 - ".standard.yml"
 - Appraisals
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -154,7 +156,6 @@ files:
 - lib/swifter_enum/swifter_enum_validator.rb
 - lib/swifter_enum/version.rb
 - sig/swifter_enum.rbs
-- swifter_enum.gemspec
 homepage: https://github.com/ConfusedVorlon/SwifterEnum
 licenses:
 - MIT
@@ -178,5 +179,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.8
 specification_version: 4
-summary: Active Record enum that uses a class, so you can add methods.
+summary: Swift-style enums for Rails that encapsulate behavior within your enum types
 test_files: []

data/swifter_enum.gemspec

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/swifter_enum/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "swifter_enum"
-  spec.version = SwifterEnum::VERSION
-  spec.authors = ["Rob Jonson"]
-  spec.email = ["rob@hobbyistsoftware.com"]
-
-  spec.summary = "Active Record enum that uses a class, so you can add methods."
-  spec.description = "Simple enum for active record that takes inspiration from Swift's enums to allow you to encapsulate enum logic within an enum class. This is easy to drop-in as a replacement for regular rails enums, with minimal changes required. Once you switch, then you can easily extend your enums with methods."
-  spec.homepage = "https://github.com/ConfusedVorlon/SwifterEnum"
-  spec.license = "MIT"
-
-  # I'm using 3.2 and above. If you're willing/able to test on lower rubies, then please let me know and feel free to change this.
-  spec.required_ruby_version = ">= 3.2.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ConfusedVorlon/SwifterEnum"
-  spec.metadata["changelog_uri"] = "https://github.com/ConfusedVorlon/SwifterEnum"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "activerecord", ">= 7.0", "< 9.0"
-  spec.add_dependency "activesupport", ">= 7.0", "< 9.0"
-  spec.add_dependency "activemodel", ">= 7.0", "< 9.0"
-
-  # Specify development dependencies
-  spec.add_development_dependency "sqlite3", ">= 1.4"
-  spec.add_development_dependency "minitest", "~> 5.22"
-  spec.add_development_dependency "debug"
-  spec.add_development_dependency "appraisal", "~> 2.4"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end