enum_kit 0.1.0

data/lib/enum_kit/active_record_patches/validations/pg_enum_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module Validations
+    # Validates whether an enum's value is acceptable by comparing with the acceptable values defined in the PostgreSQL
+    # database.
+    #
+    class PgEnumValidator < ActiveModel::EachValidator
+      # Validate the given value is acceptable for the enum.
+      #
+      # @param record    [ActiveRecord::Base]  The record being validated.
+      # @param attribute [Symbol]              The enum attribute being validated.
+      # @param value     [String, Symbol, nil] The current value of the enum.
+      #
+      def validate_each(record, attribute, value)
+        values = record.class.pg_enum_values(attribute)
+
+        return if values.include?(value)
+
+        record.errors.add(attribute, options[:message] || :invalid, **options.except(:message).merge!(
+          attribute: record.class.human_attribute_name(attribute),
+          values: values.join(', ')
+        ))
+      end
+    end
+  end
+end

data/lib/enum_kit/constants.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module EnumKit
+  # @return [String] The gem's semantic version number.
+  #
+  VERSION = '0.1.0'
+end

data/lib/enum_kit/helpers.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module EnumKit
+  # Makes an underscored, lowercase form from the expression in the string.
+  #
+  # Changes '::' to '/' to convert namespaces to paths.
+  # This method is based on the `ActiveSupport::Inflector.underscore` method.
+  #
+  # @param  value [String] A value to transform.
+  # @return       [String] The underscored, lowercase form of the expression.
+  #
+  def self.underscore(value)
+    return value unless /[A-Z-]|::/.match?(value)
+
+    value = value.to_s.gsub('::', '/')
+    value.gsub!('PostgreSQL', 'Postgresql')
+    value.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+    value.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+    value.tr!('-', '_')
+    value.downcase!
+    value
+  end
+
+  # Convert a value into a String that can be used in SQL.
+  #
+  # @param  value [Array|String|Symbol] A value to convert into SQL format.
+  # @return       [String]              The SQL representation of the value.
+  #
+  def self.sqlize(value)
+    case value
+    when Array
+      '(' + value.map { |v| sqlize(v) }.join(', ') + ')'
+    when String
+      ActiveRecord::Base.connection.quote(value)
+    when Symbol
+      sqlize(value.to_s)
+    else
+      raise ArgumentError, "Unable to convert value of type #{value.class} into SQL format."
+    end
+  end
+
+  # Sanitize the name of the enum.
+  #
+  # @param  name [String|Symbol] An enum name.
+  # @return      [String]        The sanitized name.
+  #
+  def self.sanitize_name!(name)
+    raise ArgumentError, 'Enum names must be a String or a Symbol.' unless name.is_a?(String) || name.is_a?(Symbol)
+
+    name = name.to_s
+
+    return name if name =~ /^[a-z0-9_]+$/
+
+    raise ArgumentError, 'Enum names may contain only lowercase letters, numbers and underscores.'
+  end
+
+  # Sanitize a single value of an enum.
+  #
+  # @param  value [String|Symbol] An enum value.
+  # @return       [Array]         The sanitized value.
+  #
+  def self.sanitize_value!(value)
+    raise ArgumentError, 'Enum values must be a String or a Symbol.' unless value.is_a?(String) || value.is_a?(Symbol)
+
+    value = value.to_s
+
+    return value if value =~ /^[a-z0-9_ ]+$/
+
+    raise ArgumentError, 'Enum values may contain only lowercase letters, numbers, underscores and spaces.'
+  end
+
+  # Sanitize the values of an enum.
+  #
+  # @param  values [Array] An Array of String or Symbol values.
+  # @return        [Array] A sanitized Array of String values.
+  #
+  def self.sanitize_values!(values)
+    return nil if values.nil?
+
+    raise ArgumentError, 'Enum values must be an Array of String and/or Symbol objects.' unless values.is_a?(Array)
+
+    values.map { |value| sanitize_value!(value) }
+  end
+end

data/lib/enum_kit.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+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
+end
+
+EnumKit.load!

data/spec/active_record/base_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec.describe ActiveRecord::Base do
+  describe '.pg_enum' do
+    it 'is defined' do
+      expect(described_class).to respond_to(:pg_enum)
+    end
+  end
+
+  describe '.pg_enum_values' do
+    it 'is defined' do
+      expect(described_class).to respond_to(:pg_enum_values)
+    end
+  end
+end

data/spec/active_record/connection_adapters/postgresql_adapter_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+RSpec.describe ActiveRecord::ConnectionAdapters::PostgreSQLAdapter do
+  subject(:connection) { ActiveRecord::Base.connection }
+
+  describe '#create_enum' do
+    after { connection.execute 'DROP TYPE IF EXISTS an_enum' }
+
+    it 'is defined' do
+      expect(connection).to respond_to(:create_enum)
+    end
+
+    context 'when called with valid arguments' do
+      subject { connection.create_enum(:an_enum, [:first_value, 'second value']) }
+
+      it 'creates an enum' do
+        expect(subject.result_status).to eq(PG::PGRES_COMMAND_OK)
+      end
+    end
+
+    context 'when called with a malformed name' do
+      subject { connection.create_enum('an enum', [:first_value, 'second value']) }
+
+      it 'raises an ArgumentError' do
+        expect { subject }.to raise_exception(ArgumentError)
+      end
+    end
+
+    context 'when called with malformed values' do
+      subject { connection.create_enum(:an_enum, [:good_value, 'bad$value']) }
+
+      it 'raises an ArgumentError' do
+        expect { subject }.to raise_exception(ArgumentError)
+      end
+    end
+  end
+
+  describe '#drop_enum' do
+    before { connection.execute "CREATE TYPE an_enum AS ENUM ('first', 'second')" }
+    after  { connection.execute 'DROP TYPE IF EXISTS an_enum' }
+
+    it 'is defined' do
+      expect(connection).to respond_to(:drop_enum)
+    end
+
+    context 'when called with an existing enum' do
+      subject { connection.drop_enum(:an_enum) }
+
+      it 'drops the enum' do
+        expect(subject.result_status).to eq(PG::PGRES_COMMAND_OK)
+      end
+    end
+
+    context 'when called with a non-existent enum' do
+      subject { connection.drop_enum(:non_existent_enum) }
+
+      it 'raises ActiveRecord::StatementInvalid' do
+        expect { subject }.to raise_exception(ActiveRecord::StatementInvalid)
+      end
+    end
+  end
+end

data/spec/active_record/validations/pg_enum_validator_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+RSpec.describe ActiveRecord::Validations::PgEnumValidator do
+  subject { Shirt.create(name: 'Plain Shirt', size: :small) }
+
+  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
+  end
+
+  it 'rejects unknown values' do
+    expect { subject.update!(size: :other) }.to raise_exception(ActiveRecord::RecordInvalid)
+  end
+
+  it 'rejects nil values' do
+    expect { subject.update!(size: nil) }.to raise_exception(ActiveRecord::RecordInvalid)
+  end
+end

data/spec/enum_kit/constants_spec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec.describe EnumKit do
+  describe '::VERSION' do
+    subject { described_class::VERSION }
+
+    it 'is semantic' do
+      expect(subject).to match(/[0-9]+\.[0-9]+\.[0-9]+/)
+    end
+  end
+end

data/spec/enum_kit/helpers_spec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+RSpec.describe EnumKit do
+  describe '.underscore' do
+    it 'converts camel case into snake case' do
+      expect(described_class.underscore('EnumKit')).to eq('enum_kit')
+    end
+
+    it 'converts namespaces into paths' do
+      expect(described_class.underscore('EnumKit::Example')).to eq('enum_kit/example')
+    end
+
+    it 'treats PostgreSQL as an acronym' do
+      expect(described_class.underscore('PostgreSQL')).to eq('postgresql')
+    end
+  end
+
+  describe '.sqlize' do
+    context 'with a String' do
+      subject { described_class.sqlize('value') }
+
+      it 'returns a quoted String' do
+        expect(subject).to eq("'value'")
+      end
+    end
+
+    context 'with a Symbol' do
+      subject { described_class.sqlize(:value) }
+
+      it 'returns a quoted String' do
+        expect(subject).to eq("'value'")
+      end
+    end
+
+    context 'with an Array' do
+      subject { described_class.sqlize(%i[one two three]) }
+
+      it 'returns a SQL array representation' do
+        expect(subject).to eq("('one', 'two', 'three')")
+      end
+    end
+  end
+
+  describe '.sanitize_name!' do
+    it 'permits lowercase letters' do
+      expect(described_class.sanitize_name!('abc')).to eq('abc')
+    end
+
+    it 'permits numbers' do
+      expect(described_class.sanitize_name!('123')).to eq('123')
+    end
+
+    it 'permits underscores' do
+      expect(described_class.sanitize_name!('_')).to eq('_')
+    end
+
+    it 'rejects hyphens' do
+      expect { described_class.sanitize_name!('-') }.to raise_exception(ArgumentError)
+    end
+
+    it 'rejects spaces' do
+      expect { described_class.sanitize_name!(' ') }.to raise_exception(ArgumentError)
+    end
+
+    it 'rejects uppercase letters' do
+      expect { described_class.sanitize_name!('ABC') }.to raise_exception(ArgumentError)
+    end
+  end
+
+  describe '.sanitize_value!' do
+    it 'permits lowercase letters' do
+      expect(described_class.sanitize_value!('abc')).to eq('abc')
+    end
+
+    it 'permits numbers' do
+      expect(described_class.sanitize_value!('123')).to eq('123')
+    end
+
+    it 'permits spaces' do
+      expect(described_class.sanitize_value!(' ')).to eq(' ')
+    end
+
+    it 'permits underscores' do
+      expect(described_class.sanitize_value!('_')).to eq('_')
+    end
+
+    it 'rejects hyphens' do
+      expect { described_class.sanitize_value!('-') }.to raise_exception(ArgumentError)
+    end
+
+    it 'rejects uppercase letters' do
+      expect { described_class.sanitize_value!('ABC') }.to raise_exception(ArgumentError)
+    end
+  end
+
+  describe '.sanitize_values!' do
+    subject { described_class.sanitize_values!(%i[one two three]) }
+
+    it 'calls .sanitize_value! for each of the inputs' do
+      expect(described_class).to receive(:sanitize_value!).with(:one).once
+      expect(described_class).to receive(:sanitize_value!).with(:two).once
+      expect(described_class).to receive(:sanitize_value!).with(:three).once
+      subject
+    end
+  end
+end

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

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

data/spec/internal/config/database.yml

@@ -0,0 +1,3 @@
+test:
+  adapter: postgresql
+  url: <%= ENV.fetch('DATABASE_URL') { 'postgresql://127.0.0.1:5432/enum_kit_test' } %>

data/spec/internal/db/schema.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+ActiveRecord::Schema.define do
+  create_enum :shirt_size,  %w[small medium large]
+
+  create_table :shirts do |t|
+    t.string :name
+    t.enum   :size, name: :shirt_size
+  end
+end

data/spec/internal/log/.gitignore

@@ -0,0 +1 @@
+*.log

data/spec/spec_helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Conventionally, all specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The `.rspec` file contains `--require spec_helper` which will cause this file to always be loaded,
+# without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as light-weight as possible.
+# Requiring heavyweight dependencies from this file will add to the boot time of your test suite on EVERY test run,
+# even for an individual file that may not need all of that loaded. Instead, consider making a separate helper file
+# that requires the additional dependencies and performs the additional setup, and require it from the spec files
+# that actually need it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+# Bundler
+require 'bundler'
+
+Bundler.require :default, :test
+
+# Combustion
+require 'combustion'
+
+Combustion.initialize! :active_record
+
+# Rails
+require 'rspec/rails'
+
+# RSpec
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate assertion/expectation library such as wrong or the
+  # stdlib/minitest assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4.
+    # It makes the `description` and `failure_message` of custom matchers include text for helper methods defined using
+    # `chain`, e.g.:
+    #   be_bigger_than(2).and_smaller_than(4).description
+    #   # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #   # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double library (such as bogus or mocha) by changing the
+  # `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on a real object.
+    # This is generally recommended, and will default to `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will have no way to turn it off -- the option
+  # exists only for backwards compatibility in RSpec 3).
+  # It causes shared context metadata to be inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # This allows you to limit a spec run to individual examples or groups you care about by tagging them with `:focus`
+  # metadata. When nothing is tagged with `:focus`, all examples get run.
+  # RSpec also provides aliases for `it`, `describe`, and `context` that include `:focus` metadata: `fit`, `fdescribe`
+  # and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support the `--only-failures` and `--next-failure` CLI
+  # options. We recommend you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = 'spec/examples.txt'
+
+  # Limits the available syntax to the non-monkey patched syntax that is recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  config.disable_monkey_patching!
+
+  # Many RSpec users commonly either run the entire suite or an individual file, and it's useful to allow more verbose
+  # output when running an individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output, unless a formatter has already been configured (e.g. via a
+    # command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the end of the spec run, to help surface which specs are
+  # running particularly slow.
+  # config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an order dependency and want to debug it, you
+  # can fix the order by providing the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce test failures related to randomization by
+  # passing the same `--seed` value as the one that triggered the failure.
+  Kernel.srand config.seed
+end
+
+Dir[File.expand_path('support/**/*.rb', __dir__)].each { |path| require(path) }