enum_kit 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b664ac9606a62da83707c8dbb8d568692c270492d850d3137d25ccb9690d6cd5
-  data.tar.gz: 97829f364eb1da0366dd85fb5f3b898a128b62f5af8c460fe53976a96467af68
+  metadata.gz: e30bee3ea7d57c8fbaf1ac5ca571ee023eb3beb8721572c27192387007b72146
+  data.tar.gz: 87646c8ab4a8945d937d65724bfa83df77e080b81d9242c67efb4f9bba87f861
 SHA512:
-  metadata.gz: 2d28e48493d25bf2eb094dce0adf8c37c457959d70b30071e18dca1d9466749852925db512cc96584a8dbe535daaca07c59cbc1685651d2fa8590ca7af747629
-  data.tar.gz: c64d4bf2f48a506f7ce4056b7de079c3dd423e4a3e8f687b1fc89391e03eb441b477ef0511cc48b697d8ffeb1a4e488ae42e5ad75f557586ac7a4583d8fdb662
+  metadata.gz: f3241b467c772bf71e2b9383babebc3de084578f8a95a7a96ccb84a44a1c00e2576c0b9d635b40f78b2327b7a879079068e6dc5146f8d6c2820880992dd105d6
+  data.tar.gz: c0564d3bb4188e180366645e6527b30058d058012edbfab3d0f915272ec766e764318b7a52f9207691a53851e6d5523fec8fea3d5cc1dc6f3187e5774ed2b217

data/.rbenv-gemsets

@@ -0,0 +1 @@
+enum_kit

data/README.md

@@ -13,13 +13,16 @@ You can install **EnumKit** using the following command:
 Or, by adding the following to your `Gemfile`:
 
 ```ruby
-gem 'enum_kit', '~> 0.1'
+gem 'enum_kit', '~> 0.3'
 ```
 
 ### Usage
 
-Here's a sample migration file which creates the enum `:shirt_size`, then adds the column `:size` to the `:shirts`
-table using the `:shirt_size` enum as the underlying type:
+Here is an example migration file that creates an enum called `:shirt_size` and then adds it to the `:shirts` table
+using the column name `:size`:
+
+*Pro Tip:* You can omit the `:enum_type` attribute when the name of the enum you want to use exactly matches the name
+of the column you're adding.
 
 ```ruby
 class CreateShirts < ActiveRecord::Migration[6.0]
@@ -28,7 +31,7 @@ class CreateShirts < ActiveRecord::Migration[6.0]
 
     create_table :shirts do |t|
       t.string :name
-      t.enum   :size, name: :shirt_size
+      t.enum   :size, enum_type: :shirt_size
 
       t.timestamps
     end
@@ -36,18 +39,18 @@ class CreateShirts < ActiveRecord::Migration[6.0]
 end
 ```
 
-You can remove the enum later using something similar to this:
+You can also remove an enum from the database, but you'll need to remove any associated columns first:
 
 ```ruby
 class DropShirts < ActiveRecord::Migration[6.0]
   def change
-    drop_table :shirts
-    drop_enum  :shirt_size
+    remove_column :shirts, :size
+    drop_enum :shirt_size
   end
 end
 ```
 
-Once you've defined an enum in a migration file, you can use it in the associated model:
+Once you've defined an enum, you can use it in the associated model with the `#pg_enum` method:
 
 ```ruby
 class Shirt < ActiveRecord::Base
@@ -55,27 +58,23 @@ class Shirt < ActiveRecord::Base
 end
 ```
 
-Note that you don't need to define the enum's cases again.
-The `pg_enum` method automatically queries the database when Rails boots for the acceptable values!
+Note that you don't need to define the enum's cases again. The `#pg_enum` method automatically queries the database
+once when the model is loaded to determine the supported values.
 
 ---
 
-When setting the enum to an unsupported value, an exception is raised. This can be problematic in cases where you don't
-have control over the input (such as when using APIs).
+When setting an enum to a value that is not supported, an exception is raised. This can be inconvenient in some cases
+such as an API where you can't control what value is submitted.
 
-To improve this, you can optionally specify that exceptions should not be raised on a per enum basis. Note that when
-opting for this feature, you'd ideally specify a validation to capture any unsupported values:
+You can disable the default 'exception raising' behaviour by adding a custom initializer to your Rails project:
 
 ```ruby
-class Shirt < ActiveRecord::Base
-  pg_enum :size, exceptions: false
-
-  validates :size, pg_enum: true
-end
+# Prevent enums from raising exceptions when set to unsupported values.
+Rails.application.config.enum_kit.disable_exceptions = true
 ```
 
-The above prevents exceptions from being raised and checks that the assigned value is one of the cases supported by the
-enum.
+Please note that this will affect *all* enums defined in your Rails app, as the `pg_enum` method simply uses the `enum`
+method behind the scenes. There isn't currently an option to set this on a per enum basis.
 
 ## Development
 

data/enum_kit.gemspec

@@ -31,5 +31,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake',        '~> 13.0'
   spec.add_development_dependency 'rspec',       '~> 3.8'
   spec.add_development_dependency 'rspec-rails', '~> 3.8'
+  spec.add_development_dependency 'rubocop',     '~> 0.77.0'
   spec.add_development_dependency 'yard',        '~> 0.9.20'
 end

data/lib/enum_kit.rb

@@ -3,60 +3,8 @@
 require 'enum_kit/constants'
 require 'enum_kit/helpers'
 
-# Used as a namespace to encapsulate the logic for the EnumKit gem.
-#
-module EnumKit
-  # Queue loading of the patches/extensions and database type registration for when `ActiveRecord` has loaded.
-  #
-  def self.load!
-    require 'active_record'
-    require 'active_record/connection_adapters/postgresql_adapter'
-    require 'active_support/lazy_load_hooks'
-
-    ActiveSupport.on_load(:active_record) do
-      EnumKit.load_patches!
-      EnumKit.load_extensions!
-      EnumKit.register_database_type!
-    end
-  end
-
-  # Load the `ActiveRecord` monkey patches.
-  #
-  def self.load_patches!
-    require 'enum_kit/active_record_patches/connection_adapters/postgresql/column_methods'
-    require 'enum_kit/active_record_patches/connection_adapters/postgresql/oid/enum'
-    require 'enum_kit/active_record_patches/connection_adapters/postgresql/oid/type_map_initializer'
-    require 'enum_kit/active_record_patches/enum'
-    require 'enum_kit/active_record_patches/enum/enum_type'
-    require 'enum_kit/active_record_patches/validations/pg_enum_validator'
-  end
-
-  # Load the `ActiveRecord` extensions.
-  #
-  def self.load_extensions!
-    %w[
-      ConnectionAdapters::PostgreSQL::ColumnDumper
-      ConnectionAdapters::PostgreSQL::SchemaDumper
-      ConnectionAdapters::PostgreSQLAdapter
-      Migration::CommandRecorder
-      SchemaDumper
-    ].each do |extension|
-      next unless Object.const_defined?("ActiveRecord::#{extension}")
-
-      require File.join('enum_kit', 'active_record_extensions', EnumKit.underscore(extension))
-
-      target_constant    = Object.const_get("ActiveRecord::#{extension}")
-      extension_constant = Object.const_get("EnumKit::ActiveRecordExtensions::#{extension}")
-
-      target_constant.prepend(extension_constant)
-    end
-  end
-
-  # Register `:enum` as a native database type.
-  #
-  def self.register_database_type!
-    ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enum] = { name: 'enum' }
-  end
+if defined?(Rails::Railtie)
+  require 'enum_kit/railtie'
+else
+  raise 'Unable to load EnumKit without Rails.'
 end
-
-EnumKit.load!

data/lib/enum_kit/active_record_patches/enum.rb

@@ -25,25 +25,11 @@ module ActiveRecord
 
     # Define a PostgreSQL enum type.
     #
-    # By default, setting an enum attribute to an unregistered value results in an exception being raised.
-    # You can disable this feature by setting the option `:exceptions` to `false` when registering the enum:
-    #   => pg_enum :size, exceptions: false
-    #
     # @param column_name [String, Symbol] The name of a column representing an enum.
-    # @param options     [Hash]           Any additional options.
     #
-    def pg_enum(column_name, options = {})
+    def pg_enum(column_name)
       values = pg_enum_values(column_name).map { |v| [v.to_sym, v.to_s] }
-
       enum(column_name => Hash[values])
-
-      enum = type_for_attribute(column_name)
-
-      raise 'Expected an ActiveRecord::Enum::EnumType' unless enum.is_a?(ActiveRecord::Enum::EnumType)
-
-      enum.disable_exceptions = options.key?(:exceptions) && !options[:exceptions]
-
-      nil
     end
   end
 end

data/lib/enum_kit/active_record_patches/enum/enum_type.rb

@@ -9,14 +9,11 @@ module ActiveRecord
     # :nodoc:
     #
     class EnumType < Type::Value
-      # @return [Boolean] Whether to prevent an exception from being raised when the enum is set to an invalid value.
-      #
-      attr_accessor :disable_exceptions
-
       # :nodoc:
       #
       def assert_valid_value(value)
-        return value if value.blank? || mapping.key?(value) || mapping.value?(value) || disable_exceptions
+        return value if value.blank? || mapping.key?(value) || mapping.value?(value)
+        return value if Rails.application.config.enum_kit.disable_exceptions
 
         raise ArgumentError, "'#{value}' is not a valid #{name}"
       end

data/lib/enum_kit/constants.rb

@@ -3,5 +3,5 @@
 module EnumKit
   # @return [String] The gem's semantic version number.
   #
-  VERSION = '0.2.3'
+  VERSION = '0.3.0'
 end

data/lib/enum_kit/railtie.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module EnumKit
+  # ...
+  #
+  class Railtie < Rails::Railtie
+    initializer 'enum_kit.set_configs' do |app|
+      app.configure do
+        config.enum_kit = ActiveSupport::OrderedOptions.new
+        config.enum_kit.disable_exceptions = false
+      end
+    end
+
+    initializer 'enum_kit.active_support.register_active_record_handler', after: 'active_support.set_configs' do
+      ActiveSupport.on_load(:active_record) do
+        # Require the ActiveRecord patches.
+        require 'enum_kit/active_record_patches/connection_adapters/postgresql/column_methods'
+        require 'enum_kit/active_record_patches/connection_adapters/postgresql/oid/enum'
+        require 'enum_kit/active_record_patches/connection_adapters/postgresql/oid/type_map_initializer'
+        require 'enum_kit/active_record_patches/enum'
+        require 'enum_kit/active_record_patches/enum/enum_type'
+        require 'enum_kit/active_record_patches/validations/pg_enum_validator'
+
+        # Require the ActiveRecord extensions.
+        %w[
+          ConnectionAdapters::PostgreSQL::ColumnDumper
+          ConnectionAdapters::PostgreSQL::SchemaDumper
+          ConnectionAdapters::PostgreSQLAdapter
+          Migration::CommandRecorder
+          SchemaDumper
+        ].each do |extension|
+          next unless Object.const_defined?("ActiveRecord::#{extension}")
+
+          require File.join('enum_kit', 'active_record_extensions', EnumKit.underscore(extension))
+
+          target_constant    = Object.const_get("ActiveRecord::#{extension}")
+          extension_constant = Object.const_get("EnumKit::ActiveRecordExtensions::#{extension}")
+
+          target_constant.prepend(extension_constant)
+        end
+
+        # Register `:enum` as a native database type.
+        ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:enum] = { name: 'enum' }
+      end
+    end
+  end
+end

data/spec/active_record/validations/pg_enum_validator_spec.rb

@@ -1,19 +1,22 @@
 # frozen_string_literal: true
 
 RSpec.describe ActiveRecord::Validations::PgEnumValidator, :unit do
-  subject { Shirt.create(name: 'Plain Shirt', size: :small) }
+  subject { Shirt.create(name: 'Plain Shirt', size: :medium) }
 
-  it 'permits known values' do
-    expect { subject.update!(size: :large) }.not_to raise_exception
-    expect { subject.update!(size: :medium) }.not_to raise_exception
-    expect { subject.update!(size: :small) }.not_to raise_exception
+  it 'passes validation when using supported values' do
+    %i[small medium large].each do |size|
+      expect(subject.update(size: size)).to eq(true)
+      expect(subject).to be_valid
+    end
   end
 
-  it 'rejects unknown values' do
-    expect { subject.update!(size: :other) }.to raise_exception(ActiveRecord::RecordInvalid)
+  it 'fails validation when using an unsupported value' do
+    expect(subject.update(size: :other)).to eq(false)
+    expect(subject).not_to be_valid
   end
 
-  it 'rejects nil values' do
-    expect { subject.update!(size: nil) }.to raise_exception(ActiveRecord::RecordInvalid)
+  it 'fails validation when using nil' do
+    expect(subject.update(size: nil)).to eq(false)
+    expect(subject).not_to be_valid
   end
 end

data/spec/internal/app/models/shirt.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Shirt < ActiveRecord::Base
-  pg_enum :size, exceptions: false
+  pg_enum :size
 
   validates :size, pg_enum: true
 end

data/spec/internal/config/initializers/enum_kit.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Prevent enums from raising exceptions when set to unsupported values.
+Rails.application.config.enum_kit.disable_exceptions = true

data/spec/spec_helper.rb

@@ -12,16 +12,16 @@
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 
-# Bundler
-require 'bundler'
-
-Bundler.require :default, :test
-
 # Combustion
 require 'combustion'
 
 Combustion.initialize! :active_record
 
+# Bundler
+require 'bundler'
+
+Bundler.require :default, :test
+
 # Rails
 require 'rspec/rails'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enum_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Nialto Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-05 00:00:00.000000000 Z
+date: 2019-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.77.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.77.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -158,6 +172,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rbenv-gemsets"
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
@@ -184,6 +199,7 @@ files:
 - lib/enum_kit/active_record_patches/validations/pg_enum_validator.rb
 - lib/enum_kit/constants.rb
 - lib/enum_kit/helpers.rb
+- lib/enum_kit/railtie.rb
 - spec/active_record/base_spec.rb
 - spec/active_record/connection_adapters/postgresql_adapter_spec.rb
 - spec/active_record/schema_dumper_spec.rb
@@ -193,6 +209,7 @@ files:
 - spec/enum_kit/helpers_spec.rb
 - spec/internal/app/models/shirt.rb
 - spec/internal/config/database.yml
+- spec/internal/config/initializers/enum_kit.rb
 - spec/internal/db/schema.rb
 - spec/internal/log/.gitignore
 - spec/spec_helper.rb
@@ -232,6 +249,7 @@ test_files:
 - spec/enum_kit/helpers_spec.rb
 - spec/internal/app/models/shirt.rb
 - spec/internal/config/database.yml
+- spec/internal/config/initializers/enum_kit.rb
 - spec/internal/db/schema.rb
 - spec/internal/log/.gitignore
 - spec/spec_helper.rb