enum_fields 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16c4c51ce50da548a7615a7f16e39793c04b0e4daaefaf1cbb54bd78c6799a42
-  data.tar.gz: 13d3d170fde5cdcb3d626a6795afc7d81edc0699542c76bee9ca156c0e60fb5a
+  metadata.gz: b8cef70b80a3d7295656083f0f02fa89ecf8c5909159e8f3739083b6628adecb
+  data.tar.gz: 52b5ef83feac0853df498cf0e2249ba05e59cf986ffa08b56ac3145a41b559f1
 SHA512:
-  metadata.gz: 0ed2ed2ac83001fe2a952f4edd287c7178585e847d1c3e6d096c70e15a5bd6829035bb57ad0cb69565a9e20d03074649e78d2cd4732ca86f1b9ff3790250f374
-  data.tar.gz: 2226c7e0ff63d325693dab63871767aa305d01b9a4575cf3b4b365addcd2b7c7b48ccf05e1fa15edf31ebb20bbd7e8160a5a6a6f2019d69475873f45538676f2
+  metadata.gz: b302a85589635931d64c7e44d8cff16833b6b6c2041d22886e410a929e092b3ca8de55f43c22b72079a87565b9bc1e5f1c1aacbf8d4a26254665578930302079
+  data.tar.gz: '0477991e1b705e53dd5283e581dd43f38fa4ff7dc82d3428c48190ea8ddb918c0865dee701be939823aff23c22b3c535b55e574ed9dbffa00e87634fe88deeb3'

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [X.X.X] - YYYY-MM-DD
+
+## [0.4.0] - 2026-03-08
+
+- Extract out Configuration to define global configuration for all enum fields
+- Rename `validate` option to `validatable` to better reflect its purpose
+- Rename `scope` option to `scopeable` to better reflect its purpose
+- Rename `allow_nil` option to `nullable` to better reflect its purpose
+- Add `inquirable` option to control the generation of inquiry methods
+- Polymorphic validation now respects `nullable` option and falls back to the association's `optional` setting
+- Update release script to keep CHANGELOG.md up to date
+- Add Continuous Integration suite to run tests and style checks
+- Update rake release to run release script
+
+## [0.3.2] - 2026-03-08
+
+- Restored CHANGELOG.md file
+
+## [0.3.1] - 2026-03-08
+
+- Release script to simplify gem deployment
+
+## [0.3.0] - 2026-03-08
+
+- Virtual attribute support — enum metadata, property, and inquiry methods now work against user-defined methods that aren't backed by a database column
+- `scope: false` option to skip scope generation (required for virtual attributes, but useful independently)
+
+## [0.2.1] - 2026-02-25
+
+- Flexibility to array definitions, supporting more input formats
+
+## [0.2.0] - 2026-02-24
+
+- Namespace support for standalone enum field registration via `EnumFields.namespace(:name) { enum_field ... }`, decoupling definitions from ActiveRecord models
+- `EnumFields.catalog` method for a sorted, serialization-friendly view of all registered definitions across model and standalone namespaces
+
+## [0.1.2] - 2026-02-20
+
+- Global `EnumFields::Registry` for cross-model enum field lookup and introspection
+
+## [0.1.1] - 2026-02-02
+
+- Polymorphic association resolution now falls back to finding by value when key lookup fails
+
+## [0.1.0] - 2026-01-27
+
+- `validate: false` option to disable validations on an enum field
+- Validation support for columns used in polymorphic associations
+
+## [0.0.5] - 2026-01-03
+
+- Class-level value accessors for enum field definitions
+
+## [0.0.4] - 2025-11-19
+
+- `enum_fields_metadata` now returns `HashWithIndifferentAccess` instead of a plain hash
+
+## [0.0.3] - 2025-11-19
+
+- `enum_fields_metadata` instance method for accessing field metadata on model instances
+- Extracted core interface functionality into separate `Base` module
+
+## [0.0.2] - 2025-11-19
+
+- `enum_field?` class method to check whether a given attribute is a registered enum field
+
+## [0.0.1] - 2025-11-17
+
+- Initial release with core `enum_field` DSL
+- Hash and array definition formats
+- Column override support
+- Additional properties on enum values
+- Inclusion validations
+- Inquiry methods, property accessors, and human-readable labels

data/README.md

@@ -21,6 +21,45 @@ And then execute:
 bundle install
 ```
 
+## Configuration
+
+### Global Configuration
+
+Configure default behavior for all `enum_field` declarations:
+
+```ruby
+# config/initializers/enum_fields.rb
+EnumFields.configure do |config|
+  config.scopeable = true    # default: true
+  config.validatable = true  # default: true
+  config.nullable = true     # default: true
+  config.inquirable = true   # default: true
+end
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `scopeable` | `true` | Generate query scopes for each enum value |
+| `validatable` | `true` | Add inclusion validation for enum values |
+| `nullable` | `true` | Allow `nil` values in validation (polymorphic columns derive this from the association's `optional` flag instead) |
+| `inquirable` | `true` | Generate `?` inquiry methods for each enum value |
+
+Individual `enum_field` options override global configuration:
+
+```ruby
+EnumFields.configure do |config|
+  config.scopeable = false
+end
+
+class Campaign < ApplicationRecord
+  # Uses global scopeable: false
+  enum_field :stage, definitions
+
+  # Overrides global — scopes are generated for this field
+  enum_field :priority, definitions, scopeable: true
+end
+```
+
 ## Usage
 
 ### Basic Setup
@@ -215,7 +254,7 @@ Campaign.completed_stage
 
 #### Validation
 
-Automatically validates that the column value is included in the defined values (with `allow_nil: true`).
+Automatically validates that the column value is included in the defined values. By default, `nil` values are allowed (see [`nullable`](#nullable) option).
 
 ### Options
 
@@ -227,25 +266,62 @@ Map the accessor to a different database column name:
 enum_field :role, definitions, column: :user_role
 ```
 
-#### `scope`
+#### `scopeable`
 
 Controls whether query scopes are generated. Defaults to `true`. Set to `false` to skip scope generation:
 
 ```ruby
-enum_field :speed, definitions, scope: false
+enum_field :speed, definitions, scopeable: false
 ```
 
-#### `validate`
+#### `validatable`
 
 Controls whether inclusion validation is added. Defaults to `true`. Set to `false` to skip validation:
 
 ```ruby
-enum_field :speed, definitions, validate: false
+enum_field :speed, definitions, validatable: false
+```
+
+#### `nullable`
+
+Controls whether `nil` values pass validation. Defaults to `true`. Set to `false` to require a value:
+
+```ruby
+enum_field :speed, definitions, nullable: false
+```
+
+For polymorphic columns, nullability is derived from the association's `optional` flag rather than the global default. A `belongs_to` with `optional: true` allows nil; without it, nil is rejected. An explicit `nullable` option on the field still takes precedence:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :commentable, polymorphic: true, optional: true
+
+  # nil allowed — derived from optional: true
+  enum_field :commentable_type, definitions
+end
+
+class Attachment < ApplicationRecord
+  belongs_to :attachable, polymorphic: true
+
+  # nil rejected — association is required by default
+  enum_field :attachable_type, definitions
+
+  # Override: allow nil despite required association
+  enum_field :attachable_type, definitions, nullable: true
+end
+```
+
+#### `inquirable`
+
+Controls whether `?` inquiry methods are generated. Defaults to `true`. Set to `false` to skip:
+
+```ruby
+enum_field :speed, definitions, inquirable: false
 ```
 
 ### Virtual Attributes
 
-`enum_field` works with computed/virtual attributes that aren't backed by a database column. Define a method on the model and use `scope: false` and `validate: false` since those features require a real column:
+`enum_field` works with computed/virtual attributes that aren't backed by a database column. Define a method on the model and use `scopeable: false` and `validatable: false` since those features require a real column:
 
 ```ruby
 class Segment < ApplicationRecord
@@ -262,7 +338,7 @@ class Segment < ApplicationRecord
       value: "large",
       label: "Large (< 10K)",
     },
-  }, scope: false, validate: false
+  }, scopeable: false, validatable: false
 
   def size_category
     case profiles_count

data/lib/enum_fields/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module EnumFields
+  class Configuration
+    DEFAULTS = {
+      scopeable: true,
+      validatable: true,
+      nullable: true,
+      inquirable: true,
+    }.freeze
+
+    attr_accessor :scopeable, :validatable, :nullable, :inquirable
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      DEFAULTS.each { |key, value| public_send("#{key}=", value) }
+    end
+  end
+end

data/lib/enum_fields/enum_field.rb

@@ -133,6 +133,8 @@ module EnumFields
     end
 
     def define_inquiry_methods!
+      return unless column_inquirable?
+
       accessor = @accessor
       column_name = @column_name
 
@@ -158,8 +160,9 @@ module EnumFields
     def define_validation!
       return unless column_validatable?
 
-      if column_polymorphic_association_name.present?
-        define_polymorphic_validation!
+      reflection = polymorphic_reflection
+      if reflection
+        define_polymorphic_validation!(reflection)
       else
         define_standard_validation!
       end
@@ -167,15 +170,17 @@ module EnumFields
 
     def define_standard_validation!
       valid_values = @definition.values.pluck(:value)
+      allow_nil = resolve_option(:nullable)
 
       @model_class.validates(@column_name, inclusion: {
         in: valid_values,
-        allow_nil: true,
+        allow_nil: allow_nil,
       })
     end
 
-    def define_polymorphic_validation!
-      association_name = column_polymorphic_association_name
+    def define_polymorphic_validation!(reflection)
+      association_name = reflection.name
+      allow_nil = resolve_polymorphic_nullable(reflection)
       column_name = @column_name
       accessor = @accessor
 
@@ -187,29 +192,43 @@ module EnumFields
           errors.add(association_name, "must be one of: #{valid_values.join(', ')}") unless valid_values.include?(association_obj.class.name)
         else
           column_value = attributes[column_name.to_s]
-          next if column_value.nil?
+          next if column_value.nil? && allow_nil
 
           errors.add(column_name, "must be one of: #{valid_values.join(', ')}") unless valid_values.include?(column_value)
         end
       end
     end
 
-    def column_polymorphic_association_name
+    def polymorphic_reflection
       return nil unless @model_class.respond_to?(:reflect_on_all_associations)
 
-      reflection = @model_class.reflect_on_all_associations(:belongs_to).find do |r|
+      @model_class.reflect_on_all_associations(:belongs_to).find do |r|
         r.options[:polymorphic] && "#{r.name}_type" == @column_name.to_s
       end
+    end
 
-      reflection&.name
+    def resolve_polymorphic_nullable(reflection)
+      return @options[:nullable] if @options.key?(:nullable)
+
+      reflection.options.fetch(:optional, false)
     end
 
     def column_scopeable?
-      @definition.present? && @options.fetch(:scope, true)
+      @definition.present? && resolve_option(:scopeable)
     end
 
     def column_validatable?
-      @definition.present? && @options.fetch(:validate, true)
+      @definition.present? && resolve_option(:validatable)
+    end
+
+    def column_inquirable?
+      @definition.present? && resolve_option(:inquirable)
+    end
+
+    def resolve_option(key)
+      return @options[key] if @options.key?(key)
+
+      EnumFields.configuration.public_send(key)
     end
   end
 end

data/lib/enum_fields/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EnumFields
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/enum_fields.rb

@@ -8,6 +8,7 @@ require "active_support/core_ext/array/extract_options"
 require "active_support/inflector"
 require "active_record"
 
+require_relative "enum_fields/configuration"
 require_relative "enum_fields/errors"
 require_relative "enum_fields/version"
 require_relative "enum_fields/base"
@@ -21,6 +22,18 @@ module EnumFields
   autoload :Namespace
   autoload :Registry
 
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+
   def self.registry
     @registry ||= Registry.new
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enum_fields
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Kinnell Shah
@@ -60,10 +60,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/enum_fields.rb
 - lib/enum_fields/base.rb
+- lib/enum_fields/configuration.rb
 - lib/enum_fields/definition.rb
 - lib/enum_fields/enum_field.rb
 - lib/enum_fields/errors.rb