power_enum 4.2.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35edbdb441b395299aa1f20a3719b5be76944f65eece54831eae69b3ffb57a9a
-  data.tar.gz: c4a2ce79baaa5bf26e056f1e4ab2470a34d40c0456931850c0b9c4ca5c5580ff
+  metadata.gz: 1472eb40672379c9033d7bd7dc3e35d545160363f33d7b05b00e174dd05530a1
+  data.tar.gz: cdacd983f5bfe94e07bed56e4a54225a6c4c54fb3d5489aacb5beb7e5886571f
 SHA512:
-  metadata.gz: 025f11e5861f9e3a0fd9d0f5dc2d547944ae4dac506432d1e08eee1afe4117b359e41c93962006c94e3c05ced183b7c733d0681e8e0a35a7cccfdab7d0afb3f2
-  data.tar.gz: 744d9fecff6322d6faab40418ebac2d438b8140c2363b23fe20a5cfc4813002c0f3b85788849f4c4e65c86128eaa711d3f8b8d6bdc895291f5731223fb4d2529
+  metadata.gz: 5395b07f622523606b08e2d81a3a68388abe12841f7e8277a223aae2dbfb488301f2b648241c75c623e50ac968134fc9962b0022982b46262fad6749ffe73347
+  data.tar.gz: ce2caa8a50801b3f004b3d624660827d9c39bbb8298cfe1a748a949ae4d0c8908bb6cd2712179ef6705e1cb10d92bc73e6ffbd4c09c1133e8e5ffbf3c2447590

data/README.markdown

@@ -10,7 +10,8 @@ Enumerations for Rails Done Right.
 
 ## Versions
 
-* PowerEnum 4.0.X (this version) supports Rails 6.X, and Rails 7.0 (Experimental)
+* PowerEnum 4.3+ supports Rails 8.X (Experimental)
+* PowerEnum 4.0.X supports Rails 6.X, and Rails 7.0 (Experimental)
 * PowerEnum 3.X supports Rails 4.2, Rails 5.X and Rails 6.0
 * PowerEnum 2.X supports Rails 4.X and Rails 5.0
 * PowerEnum 1.X supports Rails 3.1/3.2, available here: https://github.com/albertosaurus/power_enum
@@ -53,6 +54,11 @@ See "How to use it" below for more information.
 
 ## Requirements
 
+### PowerEnum 4.3+
+
+* Ruby 3.1 or later (JRuby should work but isn't extensively tested).
+* Rails 8.X
+
 ### PowerEnum 4.0.X
 
 * Ruby 2.7 or later (JRuby should work but isn't extensively tested).
@@ -299,7 +305,7 @@ With that, your BookingStatus class will have the following methods defined:
 
 #### Class Methods
 
-##### [](*args)
+##### [](*args, &block)
 
 `BookingStatus[arg]` performs a lookup for the BookingStatus instance for the given arg. The arg value can be a
 'string' or a :symbol, in which case the lookup will be against the BookingStatus.name field. Alternatively arg can be
@@ -309,8 +315,10 @@ instance of the enum (in this case BookingStatus) as a convenience.
 The `:on_lookup_failure` option specifies the name of a *class* method to invoke when the `[]` method is unable to
 locate a BookingStatus record for arg. The default is the built-in `:enforce_none` which returns nil. There are also
 built-ins for `:enforce_strict` (raise and exception regardless of the type for arg), `:enforce_strict_literals` (raises
-an exception if the arg is a Integer or Symbol), `:enforce_strict_ids` (raises and exception if the arg is a Integer) and
-`:enforce_strict_symbols` (raises an exception if the arg is a Symbol).
+an exception if the arg is a Integer or Symbol), `:enforce_strict_ids` (raises and exception if the arg is a Integer),
+`:enforce_strict_symbols` (raises an exception if the arg is a Symbol), `:insert_new_record` (will insert a new
+record - NOTE: only supported if the DB back end implements atomic UPSERT), and `:call_block`. Alternatively set
+`:on_lookup_failure` to a proc for a more generic handler.
 
 The purpose of the `:on_lookup_failure` option is that a) under some circumstances a lookup failure is a Bad Thing and
 action should be taken, therefore b) a fallback action should be easily configurable. You can
@@ -320,6 +328,27 @@ You can also pass in multiple arguments to `[]`. This returns a list of enums co
 passed in values. Duplicates are filtered out. For example `BookingStatus[arg1, arg2, arg3]` would be equivalent to
 `[BookingStatus[arg1], BookingStatus[arg2], BookingStatus[arg3]]`.
 
+Example:
+
+```ruby
+class BookingStatus < ActiveRecord::Base
+  acts_as_enumerated on_lookup_failure: :call_block
+end
+
+# Given a BookingStatus, whose possible members are "pending", "closed", or "canceled":
+
+# Returns nil
+BookingStatus[:expired]
+
+# Returns the equivalent of BookingStatus[:pending, :closed]
+BookingStatus[:Pending, :Closed] { |klass, arg| klass[arg.to_s.downcase] }
+
+# Inserts a new record - CAVEAT EMPTOR
+BookingStatus[:expired] do |klass, arg|
+  klass.insert_new_record(arg, description: "#{arg.to_s.capitalize} - inserted inline")
+end
+```
+
 ##### contains?(arg)
 
 `BookingStatus.contains?(arg)` returns `true if` the given Symbol, String or id has a member instance in the enumeration,

data/VERSION

@@ -1 +1 @@
-4.2.0
+4.5.0

data/lib/power_enum/enumerated.rb

@@ -30,10 +30,13 @@ module PowerEnum
       #   record for arg. The default is the built-in :enforce_none which returns nil. There are also built-ins for
       #   :enforce_strict (raise and exception regardless of the type for arg), :enforce_strict_literals (raises an
       #   exception if the arg is a Integer or Symbol), :enforce_strict_ids (raises and exception if the arg is a
-      #   Integer) and :enforce_strict_symbols (raises an exception if the arg is a Symbol).  The purpose of the
-      #   :on_lookup_failure option is that a) under some circumstances a lookup failure is a Bad Thing and action
-      #   should be taken, therefore b) a fallback action should be easily configurable.  You can also give it a
-      #   lambda that takes in a single argument (The arg that was passed to +[]+).
+      #   Integer), :enforce_strict_symbols (raises an exception if the arg is a Symbol), :insert_new_record (see
+      #   below), and :call_block (See documentation for +[arg]+).
+      #   The purpose of the :on_lookup_failure option is that a) under some circumstances a lookup failure is a
+      #   Bad Thing and action should be taken, therefore b) a fallback action should be easily configurable.
+      #   You can also give it a lambda that takes in a single argument (The arg that was passed to +[]+).
+      #   Note the :insert_new_record option - it will insert a new record into the database and update the enumerations
+      #   cache. NOTE: This option is only supported where the database back end implements an atomic UPSERT operation.
       # [:name_column]
       #   Override for the 'name' column.  By default, assumed to be 'name'.
       # [:alias_name]
@@ -218,15 +221,19 @@ module PowerEnum
       # Enum lookup by Symbol, String, or id.  Returns <tt>arg<tt> if arg is
       # an enum instance.  Passing in a list of arguments returns a list of
       # enums.  When called with no arguments, returns nil.
-      def [](*args)
+      #
+      # If the given arg is not in the enumerations cache, the lookup failure handler is set to :call_block
+      # and an optional block of the form { |klass, arg| } is passed to this method, the block will be
+      # invoked with the first argument being this instance and the second the given argument.
+      def [](*args, &block)
         case args.size
         when 0
           nil
         when 1
           arg = args.first
-          Array === arg ? self[*arg] : (lookup_enum_by_type(arg) || handle_lookup_failure(arg))
+          Array === arg ? self[*arg, &block] : (lookup_enum_by_type(arg) || handle_lookup_failure(arg, &block))
         else
-          args.map{ |item| self[item] }.uniq
+          args.map{ |item| self[item, &block] }.uniq
         end
       end
 
@@ -356,13 +363,13 @@ module PowerEnum
       end
 
       # Deals with a lookup failure for the given argument.
-      private def handle_lookup_failure(arg)
+      private def handle_lookup_failure(arg, &block)
         if (lookup_failure_handler = self.acts_enumerated_on_lookup_failure)
           case lookup_failure_handler
           when Proc
             lookup_failure_handler.call(arg)
           else
-            self.send(lookup_failure_handler, arg)
+            self.send(lookup_failure_handler, arg, &block)
           end
         else
           self.send(:enforce_none, arg)
@@ -418,6 +425,33 @@ module PowerEnum
         nil
       end
 
+      # Insert a new record if +arg+ is a Symbol or a String, and flush the enumerations cache.
+      def insert_new_record(arg, description: nil)
+        if Symbol === arg || String === arg
+          value = arg.to_s
+          upsert_attributes = if column_names.include?("description")
+                                { acts_enumerated_name_column => value, description: description || value.capitalize.gsub("_", " ") }
+                              else
+                                { acts_enumerated_name_column => value }
+                              end
+
+          update_enumerations_model do
+            upsert(upsert_attributes, update_only: [], unique_by: acts_enumerated_name_column)
+          end
+          self[arg]
+        else
+          nil
+        end
+      end
+
+      private def call_block(arg, &block)
+        if block_given?
+          block.call self, arg
+        else
+          enforce_none(arg)
+        end
+      end
+
       # raise the {ActiveRecord::RecordNotFound} error.
       # @private
       private def raise_record_not_found(arg)

data/lib/power_enum/has_enumerated.rb

@@ -165,9 +165,17 @@ module PowerEnum
           when #{class_name}
             val = #{class_name}.lookup_id(arg.id)
           when String
-            val = #{class_name}.lookup_name(arg)
+            val = if #{class_name}.acts_enumerated_on_lookup_failure.to_s == 'insert_new_record'
+              #{class_name}[arg]
+            else
+              #{class_name}.lookup_name(arg)
+            end
           when Symbol
-            val = #{class_name}.lookup_name(arg.id2name)
+            val = if #{class_name}.acts_enumerated_on_lookup_failure.to_s == 'insert_new_record'
+              #{class_name}[arg.id2name]
+            else
+              #{class_name}.lookup_name(arg.id2name)
+            end
           when Integer
             val = #{class_name}.lookup_id(arg)
           when nil

data/lib/power_enum/reflection.rb

@@ -130,6 +130,11 @@ of these associations is deprecated and will be removed in the future.
       true
     end
 
+    # https://github.com/rails/rails/pull/55285
+    def deprecated?
+      false
+    end
+
     # In this case, returns [[]]
     def conditions
       [[]]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power_enum
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Trevor Squires
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-24 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -61,60 +61,60 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 description: |
   Power Enum allows you to treat instances of your ActiveRecord models as though they were an enumeration of values.
   It allows you to cleanly solve many of the problems that the traditional Rails alternatives handle poorly if at all.
@@ -159,14 +159,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Allows you to treat instances of your ActiveRecord models as though they