enum_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0edccc6b488902ea7344f63e24014979d60f2a315c79335fc959c7cfeafb1473
+  data.tar.gz: 2776e409ad4108dfaf9b504d6cdb3d43cafe3368e9889d05f27635f8240c33d6
+SHA512:
+  metadata.gz: 7f41dc0fd5399088b5d5cdc02fb2bd48fd0a1c3ff3b4fdb44d53920d9c6d4b12ece952c2d6ee9c3174423bd79d3f96b7babd1e7a107315acb35ea58a6aa8cda5
+  data.tar.gz: c43cd3f3a197c828d958de2f5374d6a8d98d1ff1d6f381ec8d1265753d081682cca917af8cd220317ca0014313812102bfe6cde7e999913ab161fac480002395

data/.gitignore

@@ -0,0 +1,46 @@
+# Packages #
+############
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+
+# Logs #
+########
+*.log
+
+# Databases #
+#############
+*.sql
+*.sqlite
+
+# OS Files #
+############
+.DS_Store
+.Trashes
+ehthumbs.db
+Icon?
+Thumbs.db
+
+# Vagrant #
+###########
+.vagrant
+
+# Ruby Files #
+##############
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+/vendor/bundle/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  Exclude:
+    - 'bin/**/*'
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 2.6.5
+services:
+  - postgresql
+before_install:
+  - gem update --system
+  - gem install bundler
+before_script:
+  - psql -c 'CREATE DATABASE enum_kit_test;' -U postgres
+env:
+  global:
+    - DATABASE_URL="postgresql://127.0.0.1:5432/enum_kit_test"

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Nialto Services
+
+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,82 @@
+# EnumKit
+
+EnumKit provides native support for PostgreSQL enums in Ruby on Rails projects.
+
+## Installation
+
+You can install **EnumKit** using the following command:
+
+  $ gem install enum_kit
+
+Or, by adding the following to your `Gemfile`:
+
+```ruby
+gem 'enum_kit', '~> 0.1'
+```
+
+### 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:
+
+```ruby
+class CreateShirts < ActiveRecord::Migration[6.0]
+  def change
+    create_enum :shirt_size, %i[small medium large]
+
+    create_table :shirts do |t|
+      t.string :name
+      t.enum   :size, name: :shirt_size
+
+      t.timestamps
+    end
+  end
+end
+```
+
+You can remove the enum later using something similar to this:
+
+```ruby
+class DropShirts < ActiveRecord::Migration[6.0]
+  def change
+    drop_table :shirts
+    drop_enum  :shirt_size
+  end
+end
+```
+
+Once you've defined an enum in a migration file, you can use it in the associated model:
+
+```ruby
+class Shirt < ActiveRecord::Base
+  pg_enum :size
+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!
+
+---
+
+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).
+
+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:
+
+```ruby
+class Shirt < ActiveRecord::Base
+  pg_enum :size, exceptions: false
+
+  validates :size, pg_enum: true
+end
+```
+
+The above prevents exceptions from being raised and checks that the assigned value is one of the cases supported by the
+enum.
+
+## Development
+
+After checking out the repo, run `bundle exec rake spec` to run the tests.
+
+To install this gem onto your machine, run `bundle exec rake install`.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'enum_kit'
+require 'irb'
+
+IRB.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/enum_kit.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'enum_kit/constants'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'enum_kit'
+  spec.version       = EnumKit::VERSION
+  spec.authors       = ['Nialto Services']
+  spec.email         = ['support@nialtoservices.co.uk']
+
+  spec.summary       = 'Native PostgreSQL enum support for Ruby on Rails.'
+  spec.homepage      = 'https://github.com/nialtoservices/enum_kit'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.metadata['yard.run'] = 'yri'
+
+  spec.add_runtime_dependency 'activerecord',  '>= 4.0.0'
+  spec.add_runtime_dependency 'activesupport', '>= 4.0.0'
+  spec.add_runtime_dependency 'pg'
+
+  spec.add_development_dependency 'bundler',     '~> 2.0'
+  spec.add_development_dependency 'combustion',  '~> 1.1'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  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 'yard',        '~> 0.9.20'
+end

data/lib/enum_kit/active_record_extensions/connection_adapters/postgresql/column_dumper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module EnumKit
+  # :nodoc:
+  #
+  module ActiveRecordExtensions
+    # :nodoc:
+    #
+    module ConnectionAdapters
+      # :nodoc:
+      #
+      module PostgreSQL
+        # :nodoc:
+        #
+        module ColumnDumper
+          # :nodoc:
+          #
+          def prepare_column_options(column)
+            spec = super
+            spec[:name] = column.sql_type.inspect if column.type == :enum
+            spec
+          end
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_extensions/connection_adapters/postgresql/schema_dumper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module EnumKit
+  # :nodoc:
+  #
+  module ActiveRecordExtensions
+    # :nodoc:
+    #
+    module ConnectionAdapters
+      # :nodoc:
+      #
+      module PostgreSQL
+        # :nodoc:
+        #
+        module SchemaDumper
+          # :nodoc:
+          #
+          def prepare_column_options(column)
+            spec = super
+            spec[:name] = column.sql_type.inspect if column.type == :enum
+            spec
+          end
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_extensions/connection_adapters/postgresql_adapter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module EnumKit
+  # :nodoc:
+  #
+  module ActiveRecordExtensions
+    # :nodoc:
+    #
+    module ConnectionAdapters
+      # :nodoc:
+      #
+      module PostgreSQLAdapter
+        # @return [String] An SQL query that returns all available enum types in the database.
+        #
+        ENUM_QUERY = <<~SQL
+          SELECT
+          pg_type.OID,
+          pg_type.typname,
+          pg_type.typtype,
+          array_to_string(array_agg(pg_enum.enumlabel ORDER BY pg_enum.enumsortorder), '\t\t', '') as values
+          FROM pg_type
+          LEFT JOIN pg_enum ON pg_enum.enumtypid = pg_type.oid
+          WHERE pg_type.typtype = 'e'
+          GROUP BY pg_type.OID, pg_type.typname, pg_type.typtype
+          ORDER BY pg_type.typname
+        SQL
+
+        # @return [Hash] The enum types available in the database.
+        #
+        def enums
+          @enums ||= select_all(ENUM_QUERY.tr("\n", ' ').strip).each_with_object({}) do |row, enums|
+            enums[row['typname'].to_sym] = row['values'].split("\t\t")
+          end
+        end
+
+        # Create a new enum type in the database.
+        #
+        # @param name   [Symbol] The name of the new enum type.
+        # @param values [Array]  The enum's acceptable values.
+        #
+        def create_enum(name, values)
+          name   = EnumKit.sanitize_name!(name)
+          values = EnumKit.sanitize_values!(values)
+
+          execute "CREATE TYPE #{name} AS ENUM #{EnumKit.sqlize(values)}"
+        end
+
+        # Drop an existing enum type from the database.
+        #
+        # @param name [Symbol] The name of the existing enum type.
+        #
+        def drop_enum(name)
+          execute "DROP TYPE #{name}"
+        end
+
+        # :nodoc:
+        #
+        def migration_keys
+          super + [:name]
+        end
+
+        # :nodoc:
+        #
+        def prepare_column_options(column, types)
+          spec = super(column, types)
+          spec[:name] = column.cast_type.type.inspect if column.type == :enum
+          spec
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_extensions/migration/command_recorder.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module EnumKit
+  # :nodoc:
+  #
+  module ActiveRecordExtensions
+    # :nodoc:
+    #
+    module Migration
+      # :nodoc:
+      #
+      module CommandRecorder
+        # :nodoc:
+        #
+        def create_enum(*args)
+          record(:create_enum, args)
+        end
+
+        # :nodoc:
+        #
+        def drop_enum(*args)
+          record(:drop_enum, args)
+        end
+
+        # :nodoc:
+        #
+        def invert_create_enum(args)
+          record(:drop_enum, args.first)
+        end
+
+        # :nodoc:
+        #
+        def invert_drop_enum(args)
+          unless args.length > 1
+            raise ::ActiveRecord::IrreversibleMigration, 'drop_enum is only reversible if given an Array of values.'
+          end
+
+          record(:create_enum, args)
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_extensions/schema_dumper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module EnumKit
+  # :nodoc:
+  #
+  module ActiveRecordExtensions
+    # :nodoc:
+    #
+    module SchemaDumper
+      # :nodoc:
+      #
+      def tables(stream)
+        export_enums(stream)
+        super
+      end
+
+      # :nodoc:
+      #
+      def export_enums(stream)
+        @connection.enums.each do |name, values|
+          values = values.map(&:inspect).join(', ')
+          stream.puts "  create_enum #{name.inspect}, [#{values}]"
+        end
+
+        stream.puts if @connection.enums.any?
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_patches/connection_adapters/postgresql/column_methods.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module ConnectionAdapters
+    # :nodoc:
+    #
+    module PostgreSQL
+      # :nodoc:
+      #
+      module ColumnMethods
+        # Create an enum column with the provided name.
+        #
+        # By default, the enum type will match the name of the column.
+        # You can change this behaviour by providing the enum type as an option under the `:name` key.
+        #
+        # @example Creating a user role.
+        #   t.enum :role, name: :user_role
+        #
+        # @param name    [String] The name of the enum column.
+        # @param options [Hash]   The options (including the name of the enum type).
+        #
+        def enum(name, options = {})
+          column(name, options[:name] || name, options.except(:name))
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_patches/connection_adapters/postgresql/oid/enum.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module ConnectionAdapters
+    # :nodoc:
+    #
+    module PostgreSQL
+      # :nodoc:
+      #
+      module OID
+        # :nodoc:
+        #
+        class Enum < Type::Value
+          # @return [String] The PostgreSQL type for the enum.
+          #
+          attr_reader :name
+
+          # :nodoc:
+          #
+          def initialize(options = {})
+            @name = options.delete(:name).to_sym
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_patches/connection_adapters/postgresql/oid/type_map_initializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module ConnectionAdapters
+    # :nodoc:
+    #
+    module PostgreSQL
+      # :nodoc:
+      #
+      module OID
+        # :nodoc:
+        #
+        class TypeMapInitializer
+          # :nodoc:
+          #
+          def register_enum_type(row)
+            register row['oid'], ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Enum.new(name: row['typname'])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module Enum
+    # :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
+
+        raise ArgumentError, "'#{value}' is not a valid #{name}"
+      end
+    end
+  end
+end

data/lib/enum_kit/active_record_patches/enum.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# :nodoc:
+#
+module ActiveRecord
+  # :nodoc:
+  #
+  module Enum
+    # Retrieve the acceptable values for the enum type associated with the given column.
+    #
+    # @param  [String, Symbol] The name of an enum column.
+    # @return [Array]          The acceptable values for the enum type associated with the column.
+    #
+    def pg_enum_values(name)
+      # Determine the PostgreSQL type name for the enum.
+      type = type_for_attribute(name)
+      type = type.instance_eval { subtype } if type.is_a?(ActiveRecord::Enum::EnumType)
+
+      # Query the PostgreSQL database for the enum's acceptable values.
+      connection.enums[type.name]
+    end
+
+    # Define a PostgreSQL enum type.
+    #
+    # @param name    [String] The name of an enum column.
+    # @param options [Hash]   The options.
+    #
+    def pg_enum(name, options = {})
+      values = pg_enum_values(name).map { |value| [value.to_sym, value.to_s] }
+
+      enum(name => Hash[values])
+
+      enum = type_for_attribute(name)
+      enum.disable_exceptions = options.key?(:exceptions) && !options[:exceptions]
+
+      nil
+    end
+  end
+end