discriminable 2.2.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77f7e596256a4d211a4437b0a52d9e0f40d03a038e48c5ce6332083f7f910da9
-  data.tar.gz: cdaf98658eea3b2faf0bd6193c38fd83d010141c08d7c8cff643f331b51c0986
+  metadata.gz: 3f3be0fa32d9828b9d37795c4f04974db45b399b1b729701cc3466bc5136ac2a
+  data.tar.gz: 5e0039a3a78058800f9ae0924146eba632ad3784457c13b448d98cc174b73466
 SHA512:
-  metadata.gz: eabc2a7dd9bbbce30010f777ffc782e9f875f4c9b5c67daa2d762c224a4493b6f48d74a52b43696de29f0ef2de57128c52e2e83612362e78f896645594e5ef95
-  data.tar.gz: da4b9c0a03acca87af217b97d996077d8d60e79fe43bf1dc0baaacde5c465b3911ce0259422382c0c9ec0a3aaeea70adaf738aa62d36f1401c0763d3f6f4fa44
+  metadata.gz: ea6a3450967d34c3e275ba4da051463bd1ca9d5a2f79d483edaad6bb5b284bb76bcc498b1ad54b87df62f79728bf1665112a7409c1b621716b813d02201b8c54
+  data.tar.gz: 9cfbe503697d09f795ff4477031ed3afd66e67fc53f01c2a7a226ec6b335eb16ea655fe821ffc4a828afab1c8f2964b16674c47db37491a9619e6a4f3be6720f

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 ## [Unreleased]
 
+## [3.0.0](https://github.com/gregorw/discriminable/compare/v2.2.5...v3.0.0) (2022-08-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* get rid of legacy hash notation
+
+### Features
+
+* Alternate syntax using attribute/value instead of prepositions ([d0843e4](https://github.com/gregorw/discriminable/commit/d0843e4fdf7d9721c29d7259f5c8f0746d345d9b))
+
+
+### Bug Fixes
+
+* coverage ([bd862a8](https://github.com/gregorw/discriminable/commit/bd862a835fc0239f0ac59cac1e051293b4b547bc))
+* get rid of legacy hash notation ([4feda16](https://github.com/gregorw/discriminable/commit/4feda16be37df14dd159b321d3e45a16127fa922))
+
+### [2.2.5](https://github.com/gregorw/discriminable/compare/v2.2.4...v2.2.5) (2022-04-29)
+
+
+### Bug Fixes
+
+* updated description ([d14f366](https://github.com/gregorw/discriminable/commit/d14f366129b31a0b02d8e2314911a45e20ce1f92))
+
+### [2.2.4](https://github.com/gregorw/discriminable/compare/v2.2.3...v2.2.4) (2022-04-25)
+
+
+### Bug Fixes
+
+* changelog url ([3054a1a](https://github.com/gregorw/discriminable/commit/3054a1a0137d8d3cccb55d7f2f06cb392053dab0))
+* support querying when multiple values are provided ([f75190b](https://github.com/gregorw/discriminable/commit/f75190bcf33dcbddf507626bc77aa4709a594f4d))
+
 ### [2.2.3](https://github.com/gregorw/discriminable/compare/v2.2.2...v2.2.3) (2022-04-20)
 
 

data/README.md

@@ -7,24 +7,19 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/94041c5f946b64040368/maintainability)](https://codeclimate.com/github/gregorw/discriminable/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/94041c5f946b64040368/test_coverage)](https://codeclimate.com/github/gregorw/discriminable/test_coverage)
 
-Single table inheritance (STI) for Ruby on Rails models (ActiveRecord) using enum, boolean, string and integer column types.
+This is a Ruby gem that implements single-table inheritance (STI) for ActiveRecord models using string, integer and boolean column types.
 
-In other words, use any _existing_ model attribute for STI instead of storing class names in a `type` column.
-
-**Related work**
-
-The idea was originally described in [“Bye Bye STI, Hello Discriminable Model”](https://www.salsify.com/blog/engineering/bye-bye-sti-hello-discriminable-model) by Randy Burkes and this Gem has started out with [his code](https://gist.github.com/rlburkes/798e186acb2f93e787a5).
+In other words, it allows to use any (existing) model attribute to discriminate between different subclasses in your class hierarchy. This makes storing class names in a `type` column redundant.
 
+Also, it supports aliased attributes and _multiple_ values per subclass.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add discriminable
+    bundle add discriminable
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+or
 
-    $ gem install discriminable
+    gem install discriminable
 
 ## Usage
 
@@ -32,41 +27,97 @@ If bundler is not being used to manage dependencies, install the gem by executin
 class Order < ActiveRecord::Base
   include Discriminable
 
-  enum state: { open: 0, completed: 1 }
-  discriminable state: { open: "Cart" }
+  discriminable_attribute :state
 end
 
 class Cart < Order
+  discriminable_value :open
 end
 
 Cart.create
-=> #<Cart id: 1, state: "open">
+# => #<Cart id: 1, state: "open">
 Order.all
-=> #<ActiveRecord::Relation [#<Cart id: 1, state: "open">]>
+# => #<ActiveRecord::Relation [#<Cart id: 1, state: "open">]>
 ```
 
-### Alternative syntax
+## Features
 
-Instead of defining subclass names within the parent you may prefer to be open for extension but closed for modification (open-closed principle) using the alternative syntax.
+### Compatible with enums
 
 ```ruby
 class Order < ActiveRecord::Base
   include Discriminable
 
-  enum state: { open: 0, completed: 1 }
-  discriminable_by :state
+  enum state: { open: 0, processing: 1, invoiced: 2 }
+
+  discriminable_attribute :state
 end
 
 class Cart < Order
-  discriminable_as :open
+  discriminable_value :open
 end
 
-Cart.create
-=> #<Cart id: 1, state: "open">
-Order.all
-=> #<ActiveRecord::Relation [#<Cart id: 1, state: "open">]>
+class Invoice < Order
+  discriminable_value :invoiced
+end
+```
+
+### Aliased attributes
+
+In case you are working with a legacy database and cannot change the column name easily it’s easy to reference an aliased attribute in the `discriminable_attribute` definition.
+
+```ruby
+class Property < ActiveRecord::Base
+  include Discriminable
+
+  alias_attribute :kind, :kind_with_legacy_postfix
+
+  # Aliased attributes are supported when specifying the discriminable attribute
+  discriminable_attribute :kind
+end
+
+class NumberProperty < Property
+  discriminable_value 1
+end
 ```
 
+### Multiple values
+
+Sometimes, in a real project, you may want to map a number of values to a single class. This is possible by specifying:
+
+```ruby
+class OptionProperty < Property
+  # The first mention becomes the default value
+  discriminable_values 2, 3, 4
+end
+```
+
+Note that when creating new records with e.g. `OptionProperty.create` a _default_ value needs to be set in the database for this discriminable class. The Discriminable gem uses the _first_ value in the list as the default.
+
+
+## Comparison with standard Rails
+
+
+### Rails STI
+
+| *values* | string | integer | boolean | enum | decimal | … |
+|--|--|--|--|--|--|--|
+| single | 🟡 `class.name` only | 🔴 |  🔴 |  🔴 |  🔴 |  🔴 |
+| multiple | 🔴 | 🔴 |  🔴 |  🔴 |  🔴 |  🔴 |
+
+### Discriminable Gem
+
+| *values* | string | integer | boolean | enum | decimal | … |
+|--|--|--|--|--|--| --|
+| single | 🟢 | 🟢 |  🟢 |  🟢 |  🟢 | 🟢 |
+| multiple | 🟢 | 🟢 |  🟢 |  🟢 |  🟢 | 🟢 |
+
+“Multiple” means that more than one value can map to a single subclass. This may or may not be useful for your use case. In standard Rails, the a single class name obviously maps to a single class.
+
+## Prerequisits
+
+Rails 5+ is required.
+
 
 ## Contributing
 
@@ -79,3 +130,14 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the Discriminable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/gregorw/discriminable/blob/main/CODE_OF_CONDUCT.md).
+
+## Related work
+
+The idea for this Gem was influenced by [“Bye Bye STI, Hello Discriminable Model”](https://www.salsify.com/blog/engineering/bye-bye-sti-hello-discriminable-model) by Randy Burkes. This Gem has started out with [his code](https://gist.github.com/rlburkes/798e186acb2f93e787a5).
+
+See also:
+
+- Rails [single table inheritance](https://api.rubyonrails.org/classes/ActiveRecord/Inheritance.html) and [DelegatedType](https://api.rubyonrails.org/classes/ActiveRecord/DelegatedType.html)
+- Java [JPA discrimanator](https://openjpa.apache.org/builds/1.0.2/apache-openjpa-1.0.2/docs/manual/jpa_overview_mapping_discrim.html)
+- Python [model inheritance](https://docs.djangoproject.com/en/4.0/topics/db/models/#model-inheritance-1)
+- [Discriminator](https://github.com/gdpelican/discriminator) gem.

data/TODO.md

@@ -1,10 +1,16 @@
 - [x] multiple values per subclass
 - [x] default to first value when using hash syntax
 - [x] open-closed principle
-- [ ] Bug: multiple values: Child.all query
-- [ ] more tests / examples
-- [ ] Rails 5 support
+- [x] Bug: multiple values: Child.all query (double-check)
+- [x] can we use `type` column? => yes
+- [x] Factory Bot: create :property, kind: 3 => should instantiate a child OptionProperty… => Works if constant OptionProperty is loaded
+- [x] use `type` column with enum, int, string, etc.
+- [x] ~~`self.abstract_class = true` ➔ This results in separate tables~~
+- [x] What if value is not a “discriminable” value and class cannot be found?
+- [ ] rubocop-minitest
+- [ ] more tests / examples. [alias, non-alias] ⨉ [integer, string, boolean] ⨉ [enum, non-enum] ⨉ [type-column, non-type-column] ⨉ [multiple-values, single-values] ⨉ [subclasses, subsubclasses] ⨉ [hash-syntax, ocp-syntax]
+- [ ] Documentation
 - [ ] test permitted attributes
-- [ ] `self.abstract_class = true`
-- [ ] scoping…
-- [ ] ~~use `type` column with enum, int, string, etc.~~
+- [ ] scoping… should work OOTB
+- [ ] At least document `.descendants` issue in Rails development: https://stackoverflow.com/questions/29662518/loading-class-descendants-in-rails-development
+- [ ] Rails 5 support (see rails-5 branch)

data/lib/discriminable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Discriminable
-  VERSION = "2.2.3"
+  VERSION = "3.0.0"
 end

data/lib/discriminable.rb

@@ -17,63 +17,78 @@ require "active_support"
 # class Customer < ActiveRecord::Base
 #   include Discriminable
 #
-#   discriminable state: { lead: "Lead" }
+#   discriminable_by :state
 # end
 #
 module Discriminable
   extend ActiveSupport::Concern
 
   included do
-    class_attribute :discriminable_map, instance_writer: false
-    class_attribute :discriminable_inverse_map, instance_writer: false
-    class_attribute :discriminable_values, instance_writer: false
+    class_attribute :_discriminable_map, instance_writer: false
+    class_attribute :_discriminable_inverse_map, instance_writer: false
+    class_attribute :_discriminable_values, instance_writer: false
   end
 
-  # Specify the column to use for discrimination.
+  # This adds
+  # - `discriminable_attribute` and
+  # - `discriminalbe_value`
+  # class methods (plus some aliases).
   module ClassMethods
-    def discriminable(**options)
-      raise "Subclasses should not override .discriminable" unless base_class?
-
-      attribute, map = options.first
-
-      # E.g. { value: "ClassName" }
-      self.discriminable_map = map.with_indifferent_access
+    # Specify the attribute/column at the root class to use for discrimination.
+    def discriminable_by(attribute)
+      raise "Subclasses should not override .discriminable_by" unless base_class?
 
-      # Use first key as default discriminator
-      # { a: "C", b: "C" }.invert => { "C" => :b }
-      # { a: "C", b: "C" }.to_a.reverse.to_h.invert => { "C" => :a }
-      # E.g. { "ClassName" => :value }
-      self.discriminable_inverse_map = map.to_a.reverse.to_h.invert
+      self._discriminable_map ||= _discriminable_map_memoized
+      self._discriminable_inverse_map ||= _discriminable_inverse_map_memoized
 
       attribute = attribute.to_s
       self.inheritance_column = attribute_aliases[attribute] || attribute
     end
 
-    def discriminable_by(attribute)
-      raise "Subclasses should not override .discriminable_by" unless base_class?
-
-      self.discriminable_map ||= discriminable_map_memoized
-      self.discriminable_inverse_map ||= discriminable_inverse_map_memoized
+    # “Aliases” for discriminable_by
+    def discriminable_attribute(attribute)
+      discriminable_by(attribute)
+    end
 
-      attribute = attribute.to_s
-      self.inheritance_column = attribute_aliases[attribute] || attribute
+    def discriminable_on(attribute)
+      discriminable_by(attribute)
     end
 
+    # Specify the values the subclass corresponds to.
     def discriminable_as(*values)
       raise "Only subclasses should specify .discriminable_as" if base_class?
 
-      self.discriminable_values = values.map do |value|
+      self._discriminable_values = values.map do |value|
         value.instance_of?(Symbol) ? value.to_s : value
       end
     end
 
+    def discriminable_value(*values)
+      discriminable_as(*values)
+    end
+
+    def discriminable_values(*values)
+      discriminable_as(*values)
+    end
+
     # This is the value of the discriminable attribute
     def sti_name
-      discriminable_inverse_map[name]
+      _discriminable_inverse_map[name]
+    end
+
+    def sti_names
+      ([self] + descendants).flat_map(&:_discriminable_values)
+    end
+
+    def type_condition(table = arel_table)
+      return super unless _discriminable_values.present?
+
+      sti_column = table[inheritance_column]
+      predicate_builder.build(sti_column, sti_names)
     end
 
     def sti_class_for(value)
-      return self unless (type_name = discriminable_map[value])
+      return self unless (type_name = _discriminable_map[value])
 
       super type_name
     end
@@ -85,23 +100,23 @@ module Discriminable
       attrs = attrs.to_h if attrs.respond_to?(:permitted?)
       return unless attrs.is_a?(Hash)
 
-      value = discriminable_value(attrs)
+      value = _discriminable_value(attrs)
       sti_class_for(value)
     end
 
-    def discriminable_map_memoized
+    def _discriminable_map_memoized
       Hash.new do |map, value|
-        map[value] = descendants.detect { |d| d.discriminable_values.include? value }&.name
+        map[value] = descendants.detect { |d| d._discriminable_values.include? value }&.name
       end
     end
 
-    def discriminable_inverse_map_memoized
+    def _discriminable_inverse_map_memoized
       Hash.new do |map, value|
-        map[value] = value.constantize.discriminable_values&.first
+        map[value] = value.constantize._discriminable_values&.first
       end
     end
 
-    def discriminable_value(attrs)
+    def _discriminable_value(attrs)
       attrs = attrs.with_indifferent_access
       value = attrs[inheritance_column]
       value ||= attrs[attribute_aliases.invert[inheritance_column]]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: discriminable
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 3.0.0
 platform: ruby
 authors:
 - Gregor Wassmann
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-20 00:00:00.000000000 Z
+date: 2022-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -108,8 +108,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
-description: Single Table Inheritencs (STI) like functionality using _any_ column,
-  like e.g. enums, etc.
+description: A Ruby gem that implements single-table inheritance (STI) for ActiveRecord
+  models using string, integer and boolean column types.
 email:
 - gregor.wassmann@gmail.com
 executables: []
@@ -137,7 +137,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/gregorw/discriminable
   source_code_uri: https://github.com/gregorw/discriminable
-  changelog_uri: https://github.com/gregorw/discriminable/CHANGELOG.md
+  changelog_uri: https://github.com/gregorw/discriminable/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'false'
 post_install_message:
 rdoc_options: []