unmagic-enum 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e0707a39bcaed61e94384ad0f2b80da72d62034788b7b5cfcebfe8ed11430e1
+  data.tar.gz: 0d54f6ef948a3ffe7667a28032dbab381c974578632cba85eced47f1faac99cf
+SHA512:
+  metadata.gz: c5859e7c7836a1e81752180a32c20acd9bd628e6f31dbacd9287376ba4994208dda2e13f4c10dd4ffe60dee98f7ac6f1b35e6759c728f244588c2b3384f539c6
+  data.tar.gz: 69d503aa8641966f37525bccc1216c6dd66d32a80cd1f33786b1f9700c5c2c391f270642d790c554d1ca565427750329c788965a2ac5d55c74a294b673a8b300

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-04
+
+### Added
+- Initial release
+- `Unmagic::Enum` base class for defining type-safe, immutable enums backed by string values
+- Custom attributes via `attribute :name`, with `default:` values and `alias:` reader names
+- Key/value separation (`new("entity", value: "bot")`) for mapping code identifiers to differing database values
+- Support for symbols, integers, and classes as keys (preserving original type), enabling clean STI integration
+- Dynamic query methods (`status.active?`) for checking enum keys
+- Lookups by key or value with `Enum[...]`, plus `all`, `keys`, `values`, and `valid?` helpers
+- Duplicate key and value detection, and reserved-method conflict detection, raised at definition time
+- `InvalidValueError` raised on invalid assignment, mirroring Rails enum behaviour
+- ActiveRecord integration: `Enum.column_type` for serialization, casting, and eager validation in `attribute` declarations
+- Rails presence support (`blank?`/`present?`) and JSON serialization (`as_json`)
+- Empty strings treated as `nil`
+
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/unreasonable-magic/unmagic-enum/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Pitt
+
+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,139 @@
+# Unmagic::Enum
+
+Type-safe enums with attributes for Rails applications.
+
+## Features
+
+- Type-safe enumeration values with string storage
+- Custom attributes with defaults and aliases
+- ActiveRecord integration with custom column type
+- STI (Single Table Inheritance) support
+- Query methods for checking enum values
+- Duplicate key/value detection
+- Works with symbols, integers, classes as keys
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'unmagic-enum'
+```
+
+## Usage
+
+### Basic Enum
+
+```ruby
+class Status < Unmagic::Enum
+  ACTIVE = new("active")
+  PENDING = new("pending")
+  ARCHIVED = new("archived")
+end
+
+# Usage
+status = Status::ACTIVE
+status.active?              # => true
+status == "active"          # => true
+status.to_s                 # => "active"
+Status["active"]            # => Status::ACTIVE
+```
+
+### Enum with Attributes
+
+```ruby
+class Priority < Unmagic::Enum
+  attribute :label
+  attribute :color
+  attribute :level, default: 0
+
+  HIGH = new("high", label: "High Priority", color: "red", level: 3)
+  MEDIUM = new("medium", label: "Medium Priority", color: "yellow", level: 2)
+  LOW = new("low", label: "Low Priority", color: "green", level: 1)
+end
+
+priority = Priority::HIGH
+priority.label              # => "High Priority"
+priority.color              # => "red"
+priority.level              # => 3
+```
+
+### ActiveRecord Integration
+
+```ruby
+class Message < ApplicationRecord
+  class State < Unmagic::Enum
+    DRAFT = new("draft")
+    SENT = new("sent")
+    DELIVERED = new("delivered")
+  end
+
+  # Use the column type for proper serialization
+  attribute :state, State.column_type
+  
+  # Create scopes
+  scope :delivered, -> { where(state: State::DELIVERED) }
+end
+
+# Usage
+message = Message.new(state: "sent")
+message.state               # => Message::State::SENT
+message.state.sent?         # => true
+```
+
+### Key/Value Separation
+
+Useful when database values differ from code identifiers:
+
+```ruby
+class MessageType < Unmagic::Enum
+  USER = new("user")                    # key and value both "user"
+  ENTITY = new("entity", value: "bot")  # key: "entity", value: "bot" (legacy DB)
+  SYSTEM = new("system", value: "s")    # key: "system", value: "s" (short code)
+end
+
+MessageType::ENTITY.key     # => "entity"
+MessageType::ENTITY.value   # => "bot"
+MessageType["bot"]          # => MessageType::ENTITY
+```
+
+### STI Support
+
+```ruby
+class User < ApplicationRecord
+  class Type < Unmagic::Enum
+    # Pass the actual class - no constantize needed!
+    CUSTOMER = new(Customer)
+    ADMIN = new(Admin)
+    MODERATOR = new(Moderator)
+  end
+
+  attribute :type, Type.column_type
+
+  def self.find_sti_class(type_name)
+    if enum_value = Type[type_name]
+      enum_value.key  # Returns the class directly
+    else
+      super
+    end
+  end
+end
+```
+
+## Development
+
+After checking out the repo, install dependencies and run the tests:
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/unreasonable-magic/unmagic-enum.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/unmagic/enum/active_record_extensions.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# ActiveRecord extensions for Unmagic::Enum
+# This module provides database type casting and serialization support
+module Unmagic
+  class Enum
+    module ActiveRecordExtensions
+      class ColumnType < ActiveRecord::Type::Value
+        def initialize(enum_class)
+          @enum_class = enum_class
+          super()
+        end
+
+        def type
+          :string
+        end
+
+        # Cast a value to its enum instance. Lenient, mirroring
+        # ActiveRecord::Enum::EnumType#cast: an unknown value resolves to nil
+        # rather than raising. Rejection of bad input happens eagerly, on
+        # assignment, in #assert_valid_value (the same hook Rails enums use).
+        def cast(value)
+          return nil if value.nil? || value == ''
+          return value if value.is_a?(@enum_class)
+
+          @enum_class[value.to_s]
+        end
+
+        # Deserialize a database value. Lenient like #cast (and like Rails'
+        # EnumType, which maps an unknown column value to nil) so that reading a
+        # row never raises on data the enum no longer recognises.
+        def deserialize(value)
+          return nil if value.nil? || value == ''
+
+          @enum_class[value]
+        end
+
+        # Validate a value at assignment time, the way ActiveRecord::Enum does:
+        # ActiveModel::Attribute#with_value_from_user calls this before storing,
+        # so an invalid value raises immediately on `record.attr = ...` instead
+        # of later, lazily, when the attribute is read. Blank is allowed (becomes
+        # nil); an enum instance or a known key/value passes.
+        def assert_valid_value(value)
+          return if value.nil? || value == ''
+          return if value.is_a?(@enum_class)
+          return if @enum_class[value]
+
+          raise Unmagic::Enum::InvalidValueError, "Invalid #{@enum_class.name} value: #{value.inspect}"
+        end
+
+        # Serialize value for database storage
+        def serialize(value)
+          return nil if value.nil?
+
+          value.to_s
+        end
+
+        # Check if the value has changed
+        def changed_in_place?(raw_old_value, new_value)
+          raw_old_value.to_s != new_value.to_s
+        end
+      end
+
+      module ClassMethods
+        # For ActiveRecord attribute type definition
+        def column_type
+          @column_type ||= Unmagic::Enum::ActiveRecordExtensions::ColumnType.new(self)
+        end
+      end
+
+      module InstanceMethods
+        # Support for ActiveRecord type casting in SQL queries
+        # This allows Enum instances to be used directly in where clauses
+        def to_type_for_database
+          @value
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+      end
+    end
+  end
+end

data/lib/unmagic/enum/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Enum
+    # Current version of the unmagic-enum gem
+    VERSION = "0.1.0"
+  end
+end

data/lib/unmagic/enum.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'unmagic/enum/version'
+
+# ActiveRecord is optional. We eagerly (but tolerantly) require it so that the
+# integration below activates regardless of gem load order in a Rails app. When
+# ActiveRecord isn't installed the LoadError is swallowed and the gem works as a
+# plain Ruby enum.
+begin
+  require 'active_record'
+rescue LoadError
+  # ActiveRecord is optional
+end
+
+module Unmagic
+  # Base class for creating type-safe enums with string values
+  #
+  # Basic usage:
+  #   class Status < Unmagic::Enum
+  #     ACTIVE = new("active")
+  #     PENDING = new("pending")
+  #     ARCHIVED = new("archived")
+  #   end
+  #
+  # With attributes:
+  #   class Priority < Unmagic::Enum
+  #     attribute :label
+  #     attribute :color
+  #
+  #     HIGH = new("high", label: "High Priority", color: "red")
+  #     MEDIUM = new("medium", label: "Medium Priority", color: "yellow")
+  #     LOW = new("low", label: "Low Priority", color: "green")
+  #   end
+  #
+  # Key/Value separation (useful for database migrations):
+  #   class MessageType < Unmagic::Enum
+  #     # The key is what you use in code, value is what's stored in DB
+  #     USER = new("user")                           # key and value both "user"
+  #     ENTITY = new("entity", value: "bot")         # key: "entity", value: "bot" (legacy DB)
+  #     SYSTEM = new("system", value: "s")           # key: "system", value: "s" (short code)
+  #   end
+  #
+  # Different key types (symbols, integers, classes):
+  #   class MixedEnum < Unmagic::Enum
+  #     # Keys preserve their original type
+  #     SYMBOL = new(:active)                        # key is :active (Symbol)
+  #     INTEGER = new(1, value: "one")               # key is 1 (Integer)
+  #     CLASS = new(User)                            # key is User (Class)
+  #   end
+  #
+  # STI (Single Table Inheritance) integration:
+  #   class User < ApplicationRecord
+  #     class Type < Unmagic::Enum
+  #       # Pass the actual class - no constantize needed!
+  #       CUSTOMER = new(Customer)                   # key: Customer class, value: "Customer"
+  #       ADMIN = new(Admin, value: "a")            # key: Admin class, value: "a"
+  #       MODERATOR = new(Moderator)                # key: Moderator class, value: "Moderator"
+  #     end
+  #
+  #     attribute :type, Type.column_type
+  #
+  #     # Clean STI integration - enum.key returns the actual class
+  #     def self.find_sti_class(type_name)
+  #       if enum_value = Type[type_name]
+  #         enum_value.key  # Returns the class directly, no constantize!
+  #       else
+  #         super
+  #       end
+  #     end
+  #
+  #     def self.sti_name
+  #       Type.all.find { |e| e.key == self }&.value || name
+  #     end
+  #   end
+  #
+  # Usage patterns:
+  #   status = Status::ACTIVE
+  #   status.active?                # => true (query method)
+  #   status == "active"            # => true (string equality)
+  #   status == :active             # => false (symbols don't match strings)
+  #   status.to_s                   # => "active" (for database)
+  #
+  #   # Lookups work with any type
+  #   Status["active"]              # => Status::ACTIVE
+  #   MixedEnum[:active]            # => MixedEnum::SYMBOL
+  #   MixedEnum[1]                  # => MixedEnum::INTEGER
+  #   MixedEnum[User]               # => MixedEnum::CLASS
+  #
+  class Enum
+    class InvalidValueError < StandardError; end
+    class ReservedValueError < StandardError; end
+
+    class << self
+      # Get enum instances dynamically from constants
+      def instances_by_key
+        # Build hash from constants each time (stateless)
+        constants.each_with_object({}) do |const_name, hash|
+          const = const_get(const_name)
+          next unless const.is_a?(Unmagic::Enum)
+
+          hash[const.key_string] = const
+        end
+      end
+
+      # Get enum instances by value (database value)
+      def instances_by_value
+        # Build hash from constants each time (stateless)
+        constants.each_with_object({}) do |const_name, hash|
+          const = const_get(const_name)
+          next unless const.is_a?(Unmagic::Enum)
+
+          hash[const.value] = const
+        end
+      end
+
+      # Backward compatibility - instances is an alias for instances_by_key
+      def instances
+        instances_by_key
+      end
+
+      # Declare attributes for this enum class with options
+      def attribute(*names, **options)
+        @attribute_metadata ||= {}
+
+        names.each do |name|
+          # Store metadata for this attribute
+          @attribute_metadata[name] = options
+
+          # Create the reader method
+          attr_reader name
+
+          # Create alias if specified
+          next unless options[:alias]
+
+          aliases = Array(options[:alias])
+          aliases.each do |alias_name|
+            alias_method alias_name, name
+
+            # Track reserved method names to prevent conflicts
+            @reserved_methods ||= Set.new
+            @reserved_methods.add(alias_name.to_s)
+          end
+        end
+      end
+
+      # Get declared attributes (just the names)
+      def attributes
+        @attribute_metadata&.keys || []
+      end
+
+      # Get metadata for an attribute
+      def attribute_metadata
+        @attribute_metadata || {}
+      end
+
+      # Get reserved method names (from aliases)
+      def reserved_methods
+        @reserved_methods || Set.new
+      end
+
+      # Get all enum values
+      def all
+        instances.values
+      end
+
+      # Look up enum by key or value
+      def [](lookup)
+        lookup_str = lookup.to_s
+        # Try key first, then value
+        instances_by_key[lookup_str] || instances_by_value[lookup_str]
+      end
+
+      # Alias for [] to support dry-initializer type coercion
+      # dry-initializer expects types to respond to .call with 1 argument
+      def call(value)
+        self[value]
+      end
+
+      # Get all valid database values (useful for validations)
+      def values
+        instances_by_value.keys
+      end
+
+      # Get all valid keys (identifiers used in code)
+      def keys
+        instances_by_key.keys
+      end
+
+      # Check if a value is valid for this enum
+      def valid?(value)
+        case value
+        when self
+          true
+        when String
+          instances.key?(value)
+        else
+          false
+        end
+      end
+
+      # Ensure each subclass has its own metadata
+      def inherited(subclass)
+        super
+        # Initialize metadata for attributes and reserved methods
+        subclass.instance_variable_set(:@attribute_metadata, {})
+        subclass.instance_variable_set(:@reserved_methods, Set.new)
+      end
+    end
+
+    # The key (identifier used in code - preserves original type)
+    attr_reader :key
+
+    # The key as a string (used for lookups and comparisons)
+    attr_reader :key_string
+
+    # The value (what gets stored in database)
+    attr_reader :value
+
+    # Override equality to work with strings and same-class enums
+    def ==(other)
+      if other.is_a?(Unmagic::Enum)
+        # Only equal if same class and same value
+        other.class == self.class && @value == other.value
+      elsif other.is_a?(String)
+        # Check both key_string and value for flexibility
+        [@key_string, @value].include?(other)
+      else
+        # Check if it matches the original key (for symbols, classes, etc.)
+        @key == other
+      end
+    end
+
+    # Ensure different enum classes don't match
+    def eql?(other)
+      other.is_a?(self.class) && to_s == other.to_s
+    end
+
+    # Hash code based on string value and class
+    def hash
+      [self.class, to_s].hash
+    end
+
+    # Human-readable inspect showing how to reference this enum in code
+    def inspect
+      # Find the constant name for this enum instance
+      constant_name = self.class.constants.find do |const|
+        self.class.const_get(const) == self
+      end
+
+      if constant_name
+        "#{self.class.name}::#{constant_name}"
+      else
+        # Fallback showing how to access via bracket notation
+        # Show the original key type for clarity
+        "#{self.class.name}[#{@key.inspect}]"
+      end
+    end
+
+    # Allow enum to be used directly in database queries and assignments
+    def to_str
+      to_s
+    end
+
+    # Return the database value (for serialization)
+    def to_s
+      @value
+    end
+
+    # Return the value when used in JSON
+    def as_json
+      to_s
+    end
+
+    # Initialize the enum with key and optional value
+    def initialize(key, **attributes)
+      @key = key # Keep original type (class, symbol, integer, string, etc.)
+      @key_string = key.to_s # String version for lookups and comparisons
+
+      # Extract the special 'value' option, default to string version of key
+      @value = attributes.delete(:value)&.to_s || @key_string
+
+      # Check for duplicate keys
+      if self.class.instances_by_key[@key_string]
+        raise InvalidValueError.new("Enum key '#{@key_string}' has already been defined")
+      end
+
+      # Check for duplicate values
+      existing = self.class.instances_by_value[@value]
+      if existing
+        raise InvalidValueError.new("Enum value '#{@value}' has already been defined for key '#{existing.key_string}'")
+      end
+
+      # Check for conflicts with reserved methods (using string key for query methods)
+      key_method = "#{@key_string}?"
+      if self.class.reserved_methods.include?(key_method)
+        raise ReservedValueError.new("Cannot create enum key '#{@key_string}' because it would conflict with alias method '#{key_method}'")
+      end
+
+      # Set declared attributes with defaults
+      self.class.attribute_metadata.each do |attr, metadata|
+        value = if attributes.key?(attr)
+                  attributes[attr]
+                elsif metadata.key?(:default)
+                  metadata[:default]
+                else
+                  nil
+                end
+        instance_variable_set("@#{attr}", value)
+      end
+
+      # Warn about undeclared attributes in development
+      if defined?(Rails) && Rails.env.development?
+        extra_attrs = attributes.keys - self.class.attributes
+        if extra_attrs.any?
+          warn "[Unmagic::Enum] Undeclared attributes passed to #{self.class.name}: #{extra_attrs.join(', ')}"
+        end
+      end
+
+      freeze
+    end
+
+    # Implement query methods like `user?` for checking enum keys
+    def method_missing(method_name, *args)
+      if method_name.to_s.end_with?('?')
+        key_to_check = method_name.to_s[0..-2] # Remove the '?'
+        @key_string == key_to_check # Compare string versions
+      else
+        super
+      end
+    end
+
+    # Properly handle respond_to? for query methods
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?('?') || super
+    end
+
+    # Rails presence validation support - enums are never blank
+    def blank?
+      false
+    end
+
+    # Rails presence validation support - enums are always present
+    def present?
+      true
+    end
+
+    # Load ActiveRecord extensions if ActiveRecord is available
+    if defined?(ActiveRecord)
+      require 'unmagic/enum/active_record_extensions'
+      include ActiveRecordExtensions
+    end
+  end
+end

data/lib/unmagic_enum.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "unmagic/enum"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: unmagic-enum
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Keith Pitt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A powerful enum system providing type-safe enumerations with custom attributes,
+  STI integration, and ActiveRecord support
+email:
+- keith@unreasonable-magic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/unmagic/enum.rb
+- lib/unmagic/enum/active_record_extensions.rb
+- lib/unmagic/enum/version.rb
+- lib/unmagic_enum.rb
+homepage: https://github.com/unreasonable-magic/unmagic-enum
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/unreasonable-magic/unmagic-enum
+  source_code_uri: https://github.com/unreasonable-magic/unmagic-enum
+  changelog_uri: https://github.com/unreasonable-magic/unmagic-enum/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Type-safe enums with attributes for Rails applications
+test_files: []