shiftable 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7792e05d55078e47ad4fec714ebc5aeed51c6373ba64d31e410ab8cdfe01eb44
-  data.tar.gz: d1435eb2ab87f9e81367d73036d8bf23c270eccb29157cc1eaf364da9ef8fcb2
+  metadata.gz: 678fdd1fc65199227c201ecd4346e4c0019c78747d949ac9b4dcba8b38158c24
+  data.tar.gz: 3f527ed0b2e70a2e677b006320b3e667d0512ccfcacc5bb76232129b9f37c6d0
 SHA512:
-  metadata.gz: 8fc584eefc4ab6e4bbdcbb22a3b856f8baa2dff98daf5eceb149ced8865fa5c1dc020bcf1cde2918df47f3b0545c9c1827e9f369e2131c4bb5498804c1cce37c
-  data.tar.gz: d7970f2f74a80bdd5a657e89846a5eddd54d7396cd000d3022b0ba1782336b464586ea1391a23af6ff8df6b7d6047715c571cdfb43d55145744504f5ced7e4db
+  metadata.gz: c281d086eabfbce50dcd9f3098374656a8c7536b0ce1d5e21d5262c6e205172f90930aa7120a747904d6599313c235adba0bc5487011fa7b5df0e8c90af9157b
+  data.tar.gz: 217eb1fb303dbc45ccb962bddbff8c4dc246b20351b1f1f2312b9e4ea8c4db7a90360c089b040f0276e544a38193d01feb1728bd6f3949dfe849509a12d38a64

data/CHANGELOG.md

@@ -1,7 +1,28 @@
 ## [Unreleased]
 
-## [0.4.0] - 2021-10-27
+### Added
+
+
+### Changed
+
+
+### Fixed
+
+
+### Removed
+
 
+## [0.5.0] - 2021-11-12
+### Added
+
+- Support for Polymorphic associations (see examples in specs or README)
+
+## [0.4.1] - 2021-11-10
+### Fixed
+
+- Documentation typos in README
+
+## [0.4.0] - 2021-10-27
 ### Changed
 
 - option :preflight_checks renamed to :precheck
@@ -11,7 +32,6 @@
 - Even more 100% spec coverage
 
 ## [0.3.0] - 2021-10-26
-
 ### Changed
 
 - Internal rewrite to improve maintainability
@@ -22,7 +42,6 @@
 - Even more 100% spec coverage
 
 ## [0.2.0] - 2021-10-24
-
 ### Changed
 
 - option `before_save` is now `before_shift` as originally documented
@@ -34,7 +53,6 @@
 - Documentation
 
 ## [0.1.1] - 2021-10-23
-
 ### Fixed
 
 - Github Actions build
@@ -44,7 +62,6 @@
 - Linting
 
 ## [0.1.0] - 2021-10-23
-
 ### Added
 
 - Initial release

data/README.md

@@ -104,7 +104,7 @@ end
 
 This works as you would expect with STI (single table inheritance) classes, i.e. when defined on a subclass, only the records of that class get shifted.
 
-### Multiple association on a single class
+### Multiple associations on a single class
 
 What if the captain and the spaceship have a boss... the space
 federation!  And in a run-in with their arch-Nemesis the Plinth-inth,
@@ -114,7 +114,7 @@ all federation spaceships are commandeered!  You are ruined!
 
 class Spaceship < ActiveRecord::Base
   belongs_to :space_federation
-  extend Shiftable::Collection.new belongs_to: :space_federation, has_one: :spaceship,
+  extend Shiftable::Collection.new belongs_to: :space_federation, has_many: :spaceships,
                                    before_shift: lambda { |shifting_rel:, shift_to:, shift_from:|
                                      shifting_rel.each { |spaceship| spaceship.federation_changes += 1 }
                                    }
@@ -129,6 +129,68 @@ class SpaceFederation < ActiveRecord::Base
 end
 ```
 
+### Polymorphism and has_many through
+
+```ruby
+class SpaceTreaty < ActiveRecord::Base
+  has_many :space_treaty_signature
+end
+
+class SpaceTreatySignature < ActiveRecord::Base
+  belongs_to :space_treaty
+  belongs_to :signatory, polymorphic: true
+  # When two space federations assimilate (i.e. merge) to form a single larger federation,
+  #   they become party to (i.e. signatories of) all the treaties that had been signed by either.
+  # In practical terms, this means:
+  #
+  #   surviving_federation = SpaceFederation.find(1)
+  #   assimilated_federation = SpaceFederation.find(2)
+  #   SpaceTreatySignature.where(
+  #     signatory_id: assimilated_federation_id,
+  #     signatory_type: "SpaceFederation"
+  #   ).update_all(
+  #     signatory_id: surviving_federation.id
+  #   )
+  extend Shiftable::Collection.new(
+    belongs_to: :signatory, has_many: :space_treaty_signature,
+    polymorphic_type: "SpaceFederation",
+    method_prefix: "space_federation_",
+    before_shift: lambda { |shifting_rel:, shift_to:, shift_from:|
+      # Each item in shifting_rel is an instance of the class where Shiftable::Collection is defined,
+      #   in this case: SpaceTreatySignature
+      # And each of them has a signatory which is of type "SpaceFederation",
+      #   because a polymorphic collection only targets one type.
+      # shifting_rel.each { |signature| signature.signatory == "SpaceFederation" }
+    }
+  )
+end
+
+class SpaceFederation < ActiveRecord::Base
+  has_many :space_treaty_signature, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_planets, class_name: "Planet", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_stations, class_name: "SpaceStation", through: :space_treaty_signatures, as: :signatory
+  def assimilate_from(other_federation)
+    SpaceTreatySignature.space_federation_shift_cx(shift_to: self, shift_from: other_federation)
+  end
+end
+
+# Including Planet and SpaceStation, for completeness of the example as the other "types" of polymorphic signatories
+class Planet < ActiveRecord::Base
+  has_many :space_treaty_signature, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures
+  has_many :treaty_federations, class_name: "SpaceFederation", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_stations, class_name: "SpaceStation", through: :space_treaty_signatures, as: :signatory
+end
+
+class SpaceStation < ActiveRecord::Base
+  has_many :space_treaty_signature, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures
+  has_many :treaty_federations, class_name: "SpaceFederation", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_planets, class_name: "Planet", through: :space_treaty_signatures, as: :signatory
+end
+```#<--rubocop/md-->#<--rubocop/md-->`
+
 ### Complete example
 
 Putting it all together...
@@ -148,7 +210,7 @@ class Spaceship < ActiveRecord::Base
                                before_shift: ->(shifting:, shift_to:, shift_from:) { shifting.ownership_changes += 1 }
 
   belongs_to :space_federation
-  extend Shiftable::Collection.new belongs_to: :space_federation, has_one: :spaceship,
+  extend Shiftable::Collection.new belongs_to: :space_federation, has_many: :spaceships,
                                    before_shift: lambda { |shifting_rel:, shift_to:, shift_from:|
                                      shifting_rel.each { |spaceship| spaceship.federation_changes += 1 }
                                    }
@@ -157,11 +219,47 @@ end
 class SpaceFederation < ActiveRecord::Base
   has_many :captains
   has_many :spaceships
+  has_many :space_treaty_signature, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_planets, class_name: "Planet", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_stations, class_name: "SpaceStation", through: :space_treaty_signatures, as: :signatory
+
+  def assimilate_from(other_federation)
+    SpaceTreatySignature.space_federation_shift_cx(shift_to: self, shift_from: other_federation)
+  end
 
   def all_spaceships_commandeered_by(nemesis_federation)
     Spaceship.shift_cx(shift_to: nemesis_federation, shift_from: self)
   end
 end
+class SpaceTreaty < ActiveRecord::Base
+  has_many :space_treaty_signatures
+end
+
+class SpaceTreatySignature < ActiveRecord::Base
+  belongs_to :space_treaty
+  belongs_to :signatory, polymorphic: true
+  extend Shiftable::Collection.new(
+    belongs_to: :signatory, has_many: :space_treaty_signatures,
+    polymorphic_type: "SpaceFederation",
+    method_prefix: "space_federation_"
+  )
+end
+
+# Including Planet and SpaceStation, for completeness of the example as the other "types" of polymorphic signatories
+class Planet < ActiveRecord::Base
+  has_many :space_treaty_signatures, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures
+  has_many :treaty_federations, class_name: "SpaceFederation", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_stations, class_name: "SpaceStation", through: :space_treaty_signatures, as: :signatory
+end
+
+class SpaceStation < ActiveRecord::Base
+  has_many :space_treaty_signature, as: :signatory
+  has_many :space_treaties, through: :space_treaty_signatures
+  has_many :treaty_federations, class_name: "SpaceFederation", through: :space_treaty_signatures, as: :signatory
+  has_many :treaty_planets, class_name: "Planet", through: :space_treaty_signatures, as: :signatory
+end
 ```
 
 ... stay tuned!

data/lib/shiftable/collection.rb

@@ -16,7 +16,7 @@ module Shiftable
   class Collection < Module
     # associations: belongs_to, has_many
     # options: method_prefix, before_shift
-    def initialize(belongs_to:, has_many:, method_prefix: nil, before_shift: nil)
+    def initialize(belongs_to:, has_many:, polymorphic: nil, method_prefix: nil, before_shift: nil)
       # Ruby's Module initializer doesn't take any arguments
       super()
 
@@ -35,12 +35,13 @@ module Shiftable
           has_many: has_many.to_s.to_sym
         },
         options: {
+          polymorphic: polymorphic,
           method_prefix: method_prefix,
           # will prevent the save if it returns false
           # allows for any custom logic to be run, such as setting attributes, prior to the shift (save).
           before_shift: before_shift
         },
-        type: :cx
+        type: polymorphic ? :pcx : :cx
       )
     end
 
@@ -62,11 +63,12 @@ module Shiftable
     module ShiftCollectionModulizer
       def to_mod(signature)
         prefix = signature.method_prefix
+        type = signature.type
         Module.new do
-          define_method(:"#{prefix}shift_cx_column") do
-            signature.shift_column
+          define_method(:"#{prefix}shift_#{type}_column") do
+            signature.send("shift_#{type}_column")
           end
-          define_method(:"#{prefix}shift_cx") do |shift_to:, shift_from:|
+          define_method(:"#{prefix}shift_#{type}") do |shift_to:, shift_from:|
             signature.shift_data!(shift_to: shift_to, shift_from: shift_from)
           end
         end

data/lib/shiftable/mod_signature.rb

@@ -2,8 +2,8 @@
 
 module Shiftable
   class ModSignature
-    VALID_TYPES = %i[sg cx].freeze
-    VALID_ASSOCIATIONS = { sg: %i[belongs_to has_one], cx: %i[belongs_to has_many] }.freeze
+    VALID_ASSOCIATIONS = { sg: %i[belongs_to has_one], cx: %i[belongs_to has_many], pcx: %i[belongs_to has_many] }.freeze
+    VALID_TYPES = VALID_ASSOCIATIONS.keys.dup.freeze
     DEFAULT_BEFORE_SHIFT = ->(*_) { true }
     attr_reader :associations, :options, :type, :base
 
@@ -24,6 +24,14 @@ module Shiftable
       raise ArgumentError, "exactly two distinct associations must be provided" if invalid_number_of_associations?
     end
 
+    def polymorphic_type
+      options.dig(:polymorphic, :type)
+    end
+
+    def polymorphic_as
+      options.dig(:polymorphic, :as)
+    end
+
     def invalid_type?
       !VALID_TYPES.include?(type)
     end
@@ -48,21 +56,21 @@ module Shiftable
     end
 
     def validate_relationships
-      bt = base.reflect_on_association(belongs_to)
-      raise ArgumentError, "Unable to find belongs_to: :#{belongs_to} in #{base}" unless bt
-
-      klass = bt.klass
-      hr = klass.reflect_on_association(has_rel)
-      raise ArgumentError, "Unable to find #{has_rel_name}: :#{has_rel} in #{klass}" unless hr
+      bt_reflection = base.reflect_on_association(belongs_to)
+      raise ArgumentError, "Unable to find belongs_to: :#{belongs_to} in #{base}" unless bt_reflection
+      # We can't validate any further if the reflection is polymorphic
+      return true if bt_reflection.polymorphic?
+
+      klass = bt_reflection.klass
+      has_reflection = klass.reflect_on_association(has_rel)
+      raise ArgumentError, "Unable to find #{has_rel_name}: :#{has_rel} in #{klass}" unless has_reflection
     end
 
     module CxMethods
-      def has_many
+      def has_rel
         associations[:has_many]
       end
 
-      alias has_rel has_many
-
       def shift_data!(shift_to:, shift_from:)
         validate_relationships
         shifting_rel = ShiftingRelation.new(
@@ -77,13 +85,35 @@ module Shiftable
       end
     end
 
+    module PcxMethods
+      # This method could be defined for parity, but it is never used.
+      # def has_rel
+      #   associations[:has_many]
+      # end
+
+      def shift_data!(shift_to:, shift_from:)
+        validate_relationships
+        shifting_rel = ShiftingPolymorphicRelation.new(
+          to: shift_to,
+          from: shift_from,
+          column: {
+            type: polymorphic_type,
+            as: polymorphic_as,
+            id_column: shift_pcx_column
+          },
+          base: base
+        )
+        shifting_rel.shift do |result|
+          before_shift&.call(shifting_rel: result, shift_to: shift_to, shift_from: shift_from)
+        end
+      end
+    end
+
     module SgMethods
-      def has_one
+      def has_rel
         associations[:has_one]
       end
 
-      alias has_rel has_one
-
       # Do not move record if a record already exists (we are shifting a "has_one" association, after all)
       def precheck
         options[:precheck]
@@ -97,7 +127,7 @@ module Shiftable
           column: shift_column,
           base: base
         ) do
-          !precheck || !shift_to.send(has_one)
+          !precheck || !shift_to.send(has_rel)
         end
         shifting.shift do |result|
           before_shift&.call(shifting: result, shift_to: shift_to, shift_from: shift_from)
@@ -122,9 +152,16 @@ module Shiftable
       options[:before_shift] || DEFAULT_BEFORE_SHIFT
     end
 
+    def shift_pcx_column
+      "#{polymorphic_as}_id"
+    end
+
     def shift_column
       reflection = base.reflect_on_association(belongs_to).klass.reflect_on_association(has_rel)
       reflection.foreign_key
     end
+
+    alias shift_sg_column shift_column
+    alias shift_cx_column shift_column
   end
 end

data/lib/shiftable/shifting_polymorphic_relation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Shiftable
+  # Gets data to be shifted
+  class ShiftingPolymorphicRelation < Shifting
+    include Enumerable
+
+    def polymorphic_id_column
+      column[:id_column]
+    end
+
+    def polymorphic_type_column
+      "#{column[:as]}_type"
+    end
+
+    def found?
+      result.any?
+    end
+
+    def each(&block)
+      result.each(&block)
+    end
+
+    # @return result (once it is shifted)
+    def shift
+      return false unless found?
+
+      each do |record|
+        record.send("#{polymorphic_id_column}=", to.id)
+      end
+      @run_save = yield result if block_given?
+      each(&:save) if run_save
+      result
+    end
+
+    private
+
+    def query
+      base.where(
+        polymorphic_type_column => column[:type],
+        polymorphic_id_column => from.id
+      )
+    end
+  end
+end

data/lib/shiftable/single.rb

@@ -70,7 +70,7 @@ module Shiftable
         prefix = signature.method_prefix
         Module.new do
           define_method(:"#{prefix}shift_column") do
-            signature.shift_column
+            signature.send("shift_#{signature.type}_column")
           end
           define_method(:"#{prefix}shift_single") do |shift_to:, shift_from:|
             signature.shift_data!(shift_to: shift_to, shift_from: shift_from)

data/lib/shiftable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Shiftable
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/shiftable.rb

@@ -3,6 +3,7 @@
 require_relative "shiftable/version"
 require_relative "shiftable/shifting"
 require_relative "shiftable/shifting_record"
+require_relative "shiftable/shifting_polymorphic_relation"
 require_relative "shiftable/shifting_relation"
 require_relative "shiftable/mod_signature"
 require_relative "shiftable/collection"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shiftable
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Peter Boling
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-10 00:00:00.000000000 Z
+date: 2021-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -181,6 +181,7 @@ files:
 - lib/shiftable/collection.rb
 - lib/shiftable/mod_signature.rb
 - lib/shiftable/shifting.rb
+- lib/shiftable/shifting_polymorphic_relation.rb
 - lib/shiftable/shifting_record.rb
 - lib/shiftable/shifting_relation.rb
 - lib/shiftable/single.rb