literal_enums-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01da8c12a247c4aea59cfc6595f4f5f9b5c8dd69ebdab550ba86ac7f0c5508c7
+  data.tar.gz: 4d813f97175ce52f2fe87b2accaa6e0897fc7c78c4d1e9e0b8e8e4c774e9a6ae
+SHA512:
+  metadata.gz: 15677e95690ef2605599bb96102a0223e0b2db9c9a78b93f4b627221ff359b15decdcbd5e4360ec0d2d21b9ad3d8179613c3a33b7aeb014f64ef64331d1f10f8
+  data.tar.gz: 1ee2822126919e1c1b02205378bb860116d92613eeaac2d6528aca97e0ee30ce8b98ea018b034c3f44bed8989a3fc51fb83cf5938e1dd7f4ceedc9d0d6f224fe

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Joel Drapper
+
+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,102 @@
+# literal_enums-rails
+
+Provides additional support for Rails with LiteralEnums.
+
+## Usage
+Please see `literal_enums` for further documentaiton.
+
+### ActiveJob
+
+Literal Enums are automatically serialised and deserialised for ActiveJob. You don't need to do anythign special to enable this. Just treat enums are normal arguments.
+
+### ActiveModel
+
+You can add Enum attributes to any `ActiveModel` class as an `attribute`.
+
+```ruby
+class Article < ApplicationRecord
+  class State < Enum
+    Published()
+    Unpublished()
+  end
+
+  attribute :state, Enum[State]
+end
+```
+
+Note: you need to specify exactly which Enum class the attribute is expected to be. This is so it can deserialise and cast a value to the correct member.
+
+If you're storing the values in a database, make sure the tyep of the value matches the type of the database field. If the members don't specify values, their names will be used instead.
+
+These are not the same as Rails enums as they don't add mysterious scopes and predicates to the model itself.
+
+Instead of asking the Article if it is published, you'd need to inspect the Article's state attribute directly.
+
+You can do this with a comparator e.g. `==` or with a polymorphic predicate.
+
+```ruby
+# The Rails way
+Article.published?
+
+# The Literal Enums way
+Article.state.published?
+```
+
+Scoping the predicate to the state attribute itself reduces the risk of collision. It also means the enum makes no assumptions about the business logic of your model. It may not be the case that whole article is published because the state is published.
+
+You can use Enums like any other value when writing database queries in ActiveRecord. For example, you might define a scope like this:
+
+```ruby
+scope :published -> { where(state: State::Published, publish_at: ..Time.current) }
+```
+
+You can also define associations from an enum to relevant records.
+
+```ruby
+class Article < ApplicationRecord
+  class State < Enum
+    Published()
+    Unpublished()
+
+    has_many :articles
+  end
+
+  attribute :state, Enum[State]
+end
+
+Article::State::Published.articles # returns a relation to articles with the Published state.
+```
+
+`has_many` optionally accepts a `class_name` for the model to query, as well as the name of the enum attribute.
+
+```ruby
+has_many :publication_events, class_name: "ArticlePublicationEvent", as: :publication_status
+
+# Translates to this
+def self.publication_events
+  ArticlePublicationEvent.where(publication_status: self)
+end
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "literal_enums-rails"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install literal_enums-rails
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/literal_enums/enum.rb

@@ -0,0 +1,7 @@
+class Enum
+  extend LiteralEnums::Rails::Associations
+
+  def self.[](enum)
+    LiteralEnums::Rails::EnumType.new(enum)
+  end
+end

data/lib/literal_enums/rails/associations.rb

@@ -0,0 +1,32 @@
+module LiteralEnums
+  module Rails
+    module Associations
+      private
+
+      def has_many(name, class_name: nil, as: nil)
+        class_name ||= name.to_s.classify
+        full_class_name = class_name.constantize.name
+        foreign_key = as || relative_foreign_key(self.name, relative_to: full_class_name)
+
+        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+          def #{name}
+            #{class_name}.where(#{foreign_key}: self)
+          end
+        RUBY
+      end
+
+      def relative_foreign_key(name, relative_to:)
+        path = name.split("::")
+        other_path = relative_to.split("::")
+
+        path
+          .zip(other_path)
+          .drop_while { |a, b| a == b }
+          .transpose
+          .first
+          &.join("_")
+          &.underscore()
+      end
+    end
+  end
+end

data/lib/literal_enums/rails/enum_serializer.rb

@@ -0,0 +1,22 @@
+module LiteralEnums
+  module Rails  
+    class EnumSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize?(object)
+        object.is_a? Enum
+      end
+
+      def serialize(enum)
+        super(
+          {
+            "class" => enum.class.name,
+            "value" => enum.value
+          }
+        )
+      end
+
+      def deserialize(hash)
+        hash["class"].constantize.cast(hash["value"])
+      end
+    end
+  end
+end

data/lib/literal_enums/rails/enum_type.rb

@@ -0,0 +1,22 @@
+module LiteralEnums
+  module Rails
+    class EnumType < ActiveModel::Type::String
+      def initialize(enum)
+        @enum = enum
+      end
+
+      def type
+        :enum
+      end
+
+      def cast_value(value)
+        return value if value.is_a?(@enum)
+        @enum.cast(value)
+      end
+
+      def serialize(value)
+        value.value
+      end
+    end
+  end
+end

data/lib/literal_enums/rails/railtie.rb

@@ -0,0 +1,9 @@
+module LiteralEnums
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "literal_enums.configure_active_job_serializers" do
+        ::Rails.application.config.active_job.custom_serializers << EnumSerializer
+      end
+    end
+  end
+end

data/lib/literal_enums/rails/version.rb

@@ -0,0 +1,5 @@
+module LiteralEnums
+  module Rails
+    VERSION = "1.0.0"
+  end
+end

data/lib/literal_enums/rails.rb

@@ -0,0 +1,12 @@
+require "literal_enums/rails/version"
+require "literal_enums/rails/enum_type"
+require "literal_enums/rails/enum_serializer"
+require "literal_enums/rails/associations"
+require "literal_enums/rails/railtie"
+require "literal_enums/enum"
+
+module LiteralEnums
+  module Rails
+    # Your code goes here...
+  end
+end

data/lib/tasks/literal_enums/rails_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :literal_enums_rails do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: literal_enums-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Joel Drapper
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: literal_enums
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+description: Rails support for Literal Enums.
+email:
+- joel@drapper.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/literal_enums/enum.rb
+- lib/literal_enums/rails.rb
+- lib/literal_enums/rails/associations.rb
+- lib/literal_enums/rails/enum_serializer.rb
+- lib/literal_enums/rails/enum_type.rb
+- lib/literal_enums/rails/railtie.rb
+- lib/literal_enums/rails/version.rb
+- lib/tasks/literal_enums/rails_tasks.rake
+homepage: https://github.com/joeldrapper/literal_enums-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joeldrapper/literal_enums-rails
+  source_code_uri: https://github.com/joeldrapper/literal_enums-rails
+  changelog_uri: https://github.com/joeldrapper/literal_enums-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Literal Enums in Rails.
+test_files: []