shiftable 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15d27c7c2706faf797241101fa5229f4bf707b06f4d1b7c839cc66fd7ab2ecf8
-  data.tar.gz: 0fa0fbe15096d109c2d63568101ad0589b4c684775b69b95e831289b8bfdac3d
+  metadata.gz: 8bad3e2f27677202648655a227fa9f251a595910db9146c9fdb72952657053d3
+  data.tar.gz: 481fede6aa751831cec5c19fe8849b61b081f51cfd4e5aa0a7522ecbb31b38bf
 SHA512:
-  metadata.gz: fa80c525bb2a0cfa99a82350da151412972f86a6699e1091e520d9cec40466f07789e5d1e593f8e3b720cc9e447d742acf28f2c09f5b02c61745cf8ca79084cf
-  data.tar.gz: 4abc0b5c410ba1748646122914ac768829984934e1f57b4d0483db18d0d5985b1976d69deeceabb3bf04fc5b4e3b6307056e3eeae2cffbd89e8099059cb32c07
+  metadata.gz: 050f4afb2b1ad1e81cd9209dfee0a0f1270745a02bfea84dcaff3914794349c4e6b53b01fb21873731ad05693ae0d02639ee3ade2a0f0d1b5b103fc30952e362
+  data.tar.gz: 5bfc201b247b3082a0a1836c164133f73f59f317de9664934f08bc28a6b3d00140e2c2a3fe0ed7da2a0450fcabb67c66eb28e28c3787403517eadd28fb8d8114

data/CHANGELOG.md

@@ -1,9 +1,44 @@
 ## [Unreleased]
 
-## [0.3.0] - 2021-10-26
+### Added
+
 
 ### Changed
 
+
+### Fixed
+
+
+### Removed
+
+
+## [0.5.1] - 2021-11-12
+### Fixed
+
+- Documentation typos in README
+
+## [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
+
+### Added
+
+- Even more 100% spec coverage
+
+## [0.3.0] - 2021-10-26
+### Changed
+
 - Internal rewrite to improve maintainability
 - Extreme edge cases involving incorrect configuration will raise slightly different errors.
 
@@ -12,7 +47,6 @@
 - Even more 100% spec coverage
 
 ## [0.2.0] - 2021-10-24
-
 ### Changed
 
 - option `before_save` is now `before_shift` as originally documented
@@ -24,7 +58,6 @@
 - Documentation
 
 ## [0.1.1] - 2021-10-23
-
 ### Fixed
 
 - Github Actions build
@@ -34,7 +67,6 @@
 - Linting
 
 ## [0.1.0] - 2021-10-23
-
 ### Added
 
 - Initial release
@@ -42,4 +74,11 @@
 - 100% test coverage
 
 [0.1.0]: https://github.com/pboling/shiftable/releases/tag/v0.1.0
-[0.1.1]: https://github.com/pboling/shiftable/releases/tag/v0.1.1
+
+[0.1.1]: https://github.com/pboling/shiftable/releases/tag/v0.1.1
+
+[0.2.0]: https://github.com/pboling/shiftable/releases/tag/v0.2.0
+
+[0.3.0]: https://github.com/pboling/shiftable/releases/tag/v0.3.0
+
+[0.4.0]: https://github.com/pboling/shiftable/releases/tag/v0.4.0

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/pboling/activerecord-transactionable][source]
+. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct][conduct].
+
+To submit a patch, please fork the project and create a patch with tests. Once you're happy with it send a pull request!
+
+## Contributors
+
+[![Contributors](https://contrib.rocks/image?repo=pboling/activerecord-transactionable)][contributors]
+
+Made with [contributors-img][contrib-rocks].
+
+[comment]: <> (Following links are used by README, CONTRIBUTING)
+
+[conduct]: https://github.com/pboling/activerecord-transactionable/blob/master/CODE_OF_CONDUCT.md
+
+[contrib-rocks]: https://contrib.rocks
+
+[contributors]: https://github.com/pboling/activerecord-transactionable/graphs/contributors
+
+[comment]: <> (Following links are used by README, CONTRIBUTING, Homepage)
+
+[source]: https://github.com/pboling/activerecord-transactionable/

data/README.md

@@ -5,31 +5,23 @@ Do your Spaceships belong to Captains, but sometimes a Captain will retire, and
 We've all been there. This gem provides structure around the process of "shifting" your records from one associated
 record to a new record.
 
-| Project                 |  Shiftable |
-|------------------------ | ----------------------- |
-| gem name                |  [shiftable](https://rubygems.org/gems/shiftable) |
-| license                 |  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) |
-| download rank           |  [![Downloads Today](https://img.shields.io/gem/rd/shiftable.svg)](https://github.com/pboling/shiftable) |
-| version                 |  [![Version](https://img.shields.io/gem/v/shiftable.svg)](https://rubygems.org/gems/shiftable) |
-| dependencies            |  [![Depfu](https://badges.depfu.com/badges/0412727b7e3b740b950a683eebc708e2/count.svg)](https://depfu.com/github/pboling/shiftable?project_id=32594) |
-| unit tests              |  [![unit tests](https://github.com/pboling/shiftable/actions/workflows/test.yml/badge.svg)](https://github.com/pboling/shiftable/actions) |
-| lint status             |  [![lint status](https://github.com/pboling/shiftable/actions/workflows/style.yml/badge.svg)](https://github.com/pboling/shiftable/actions) |
-| unsupported status      |  [![unsupported status](https://github.com/pboling/shiftable/actions/workflows/unsupported.yml/badge.svg)](https://github.com/pboling/shiftable/actions) |
-| test coverage           |  [![Test Coverage](https://api.codeclimate.com/v1/badges/a53aa8b7c413b950d519/test_coverage)](https://codeclimate.com/github/pboling/shiftable/test_coverage) |
-| maintainability         |  [![Maintainability](https://api.codeclimate.com/v1/badges/a53aa8b7c413b950d519/maintainability)](https://codeclimate.com/github/pboling/shiftable/maintainability) |
-| code triage             |  [![Open Source Helpers](https://www.codetriage.com/pboling/shiftable/badges/users.svg)](https://www.codetriage.com/pboling/shiftable) |
-| homepage                |  [on Github.com][homepage], [on Railsbling.com][blogpage] |
-| documentation           |  [on RDoc.info][documentation] |
-| Spread ~♡ⓛⓞⓥⓔ♡~      |  [🌏][aboutme], [👼][angelme], [💻][coderme], [![Tweet @ Peter][followme-img]][tweetme], [🌹][politicme] |
+| Project                    |  Shiftable |
+|--------------------------- | ----------------------- |
+| name, license, docs        |  [![RubyGems.org](https://img.shields.io/badge/name-shiftable-brightgreen.svg?style=flat)][rubygems] [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][license-ref] [![RubyDoc.info](https://img.shields.io/badge/documentation-rubydoc-brightgreen.svg?style=flat)][documentation] |
+| version & downloads        |  [![Version](https://img.shields.io/gem/v/shiftable.svg)][rubygems] [![Total Downloads](https://img.shields.io/gem/dt/shiftable.svg)][rubygems] [![Downloads Today](https://img.shields.io/gem/rd/shiftable.svg)][rubygems] [![Homepage](https://img.shields.io/badge/source-github-brightgreen.svg?style=flat)][source] |
+| dependencies & linting     |  [![Depfu](https://badges.depfu.com/badges/0412727b7e3b740b950a683eebc708e2/count.svg)][depfu] [![lint status](https://github.com/pboling/shiftable/actions/workflows/style.yml/badge.svg)][actions] |
+| unit tests                 |  [![supported rubies](https://github.com/pboling/shiftable/actions/workflows/supported.yml/badge.svg)][actions] [![unsupported status](https://github.com/pboling/shiftable/actions/workflows/unsupported.yml/badge.svg)][actions] |
+| coverage & maintainability |  [![Test Coverage](https://api.codeclimate.com/v1/badges/a53aa8b7c413b950d519/test_coverage)][climate_coverage] [![codecov](https://codecov.io/gh/pboling/shiftable/branch/main/graph/badge.svg?token=J1542PYN2Z)][codecov_coverage] [![Maintainability](https://api.codeclimate.com/v1/badges/a53aa8b7c413b950d519/maintainability)][climate_maintainability] [![Security Policy](https://img.shields.io/badge/security-policy-brightgreen.svg?style=flat)][security] |
+| resources                  |  [![Discussion](https://img.shields.io/badge/discussions-github-brightgreen.svg?style=flat)][gh_discussions] [![Get help on Codementor](https://cdn.codementor.io/badges/get_help_github.svg)](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github) [![Join the chat at https://gitter.im/pboling/shiftable](https://badges.gitter.im/Join%20Chat.svg)][chat] [![Blog](https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat)][blogpage] |
+| Spread ~♡ⓛⓞⓥⓔ♡~         |  [![Open Source Helpers](https://www.codetriage.com/pboling/shiftable/badges/users.svg)][code_triage] [![Liberapay Patrons](https://img.shields.io/liberapay/patrons/pboling.svg?logo=liberapay)][liberapay_donate] [![Sponsor Me](https://img.shields.io/badge/sponsor-pboling.svg?style=social&logo=github)][gh_sponsors] [🌏][aboutme] [👼][angelme] [💻][coderme] [🌹][politicme] [![Tweet @ Peter][followme-img]][tweetme] |
 
 ## Compatibility
 
 Targeted ruby compatibility is non-EOL versions of Ruby, currently 2.6, 2.7, and 3.0, but may work on older Rubies back
 to 2.0, though it is limited to 2.5 in the gemspec. Feel free to fork if you need something older! Targeted ActiveRecord
 (Rails not required) compatibility follows the same scheme
-as [Rails Security Issue maintenance policy](https://guides.rubyonrails.org/maintenance_policy.html#security-issues),
-currently 6.1, 6.0, 5.2, but it is highly likely that this code will work in any version of ActiveRecord/Rails that runs
-on Ruby 2+.
+as [Rails Security Issue maintenance policy][maintenancee_policy], currently 6.1, 6.0, 5.2, but it is highly likely that
+this code will work in any version of ActiveRecord/Rails that runs on Ruby 2+.
 
 ## Installation
 
@@ -87,7 +79,7 @@ But how can you accomplish this? If you used the `shiftable` gem, won't take but
 
 class Spaceship < ActiveRecord::Base
   belongs_to :captain
-  extend Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, preflight_checks: true,
+  extend Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, precheck: true,
                                before_shift: ->(shifting:, shift_to:, shift_from:) { shifting.ownership_changes += 1 }
 end
 ```
@@ -100,8 +92,10 @@ class Spaceship < ActiveRecord::Base
   belongs_to :captain
 
   class << self
-    include Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, preflight_checks: true,
-                                  before_shift: ->(shifting:, shift_to:, shift_from:) { shifting.ownership_changes += 1 }
+    include Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, precheck: true,
+                                  before_shift: lambda { |shifting:, shift_to:, shift_from:|
+                                    shifting.ownership_changes += 1
+                                  }
   end
 end
 ```
@@ -110,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,
@@ -120,10 +114,10 @@ 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,
-                                   before_shift: lambda do |shifting_rel:, shift_to:, shift_from:|
-    shifting_rel.each { |spaceship| spaceship.federation_changes += 1 }
-  end
+  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 }
+                                   }
 end
 
 class SpaceFederation < ActiveRecord::Base
@@ -135,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", as: :signatory },
+    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_pcx(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
+```
+
 ### Complete example
 
 Putting it all together...
@@ -150,28 +206,79 @@ end
 
 class Spaceship < ActiveRecord::Base
   belongs_to :captain
-  extend Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, preflight_checks: true,
+  extend Shiftable::Single.new belongs_to: :captain, has_one: :spaceship, precheck: true,
                                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,
-                                   before_shift: lambda do |shifting_rel:, shift_to:, shift_from:|
-    shifting_rel.each { |spaceship| spaceship.federation_changes += 1 }
-  end
+  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 }
+                                   }
 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", as: :signatory },
+    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!
 
+## More Information
+
+* RubyDoc
+  Documentation: [![RubyDoc.info](https://img.shields.io/badge/documentation-rubydoc-brightgreen.svg?style=flat)][documentation]
+* GitHub
+  Discussions: [![Discussion](https://img.shields.io/badge/discussions-github-brightgreen.svg?style=flat)][gh_discussions]
+* Live Chat on
+  Gitter: [![Join the chat at https://gitter.im/pboling/activerecord-transactionable](https://badges.gitter.im/Join%20Chat.svg)][chat]
+* Maintainer's Blog: [![Blog](https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat)][blogpage]
+
+## Code of Conduct
+
+Everyone interacting in the Shiftable project's codebases, issue trackers, chat rooms and mailing lists is expected to
+follow the [code of conduct][conduct].
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
@@ -183,14 +290,13 @@ push git commits and the created tag, and push the `.gem` file to [rubygems.org]
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/pboling/shiftable. This project is intended to
-be a safe, welcoming space for collaboration, and contributors are expected to adhere to
-the [code of conduct](https://github.com/pboling/shiftable/blob/master/CODE_OF_CONDUCT.md).
+See [CONTRIBUTING.md][contributing]
 
-## Code of Conduct
+## Contributors
 
-Everyone interacting in the Shiftable project's codebases, issue trackers, chat rooms and mailing lists is expected to
-follow the [code of conduct](https://github.com/pboling/shiftable/blob/master/CODE_OF_CONDUCT.md).
+[![Contributors](https://contrib.rocks/image?repo=pboling/shiftable)]("https://github.com/pboling/shiftable/graphs/contributors")
+
+Made with [contributors-img](https://contrib.rocks).
 
 ## Versioning
 
@@ -205,18 +311,36 @@ the [Pessimistic Version Constraint][pvc] with two digits of precision.
 For example:
 
 ```ruby
-spec.add_dependency "shiftable", "~> 0.2"
+spec.add_dependency "shiftable", "~> 0.4"
 ```
 
+## Contact
+
+Author and maintainer is Peter Boling ([@pboling][gh_sponsors]).
+
+Comments are welcome in the [GitHub Discussions][gh_discussions] board.
+
+For security-related issues see [SECURITY][security].
+
 ## License
 
 The gem is available as open source under the terms of
-the [MIT License](https://opensource.org/licenses/MIT) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-.
+the [MIT License][license] [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][license-ref].
+See [LICENSE][license] for the official [Copyright Notice][copyright-notice-explainer].
 
 * Copyright (c) 2021 [Peter H. Boling][peterboling] of [Rails Bling][railsbling]
 
-[license]: LICENSE
+[copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
+
+[gh_discussions]: https://github.com/pboling/shiftable/discussions
+
+[conduct]: https://github.com/pboling/shiftable/blob/master/CODE_OF_CONDUCT.md
+
+[security]: https://github.com/pboling/shiftable/blob/master/SECURITY.md
+
+[license]: https://github.com/pboling/shiftable/blob/master/LICENSE.txt
+
+[license-ref]: https://opensource.org/licenses/MIT
 
 [semver]: http://semver.org/
 
@@ -238,8 +362,32 @@ the [MIT License](https://opensource.org/licenses/MIT) [![License: MIT](https://
 
 [politicme]: https://nationalprogressiveparty.org
 
-[documentation]: http://rdoc.info/github/pboling/shiftable/frames
+[documentation]: https://rubydoc.info/github/pboling/shiftable/main
+
+[source]: https://github.com/pboling/shiftable/
+
+[actions]: https://github.com/pboling/shiftable/actions
+
+[issues]: https://github.com/pboling/shiftable/issues
+
+[climate_maintainability]: https://codeclimate.com/github/pboling/shiftable/maintainability
+
+[climate_coverage]: https://codeclimate.com/github/pboling/shiftable/test_coverage
 
-[homepage]: https://github.com/pboling/shiftable/
+[codecov_coverage]: https://codecov.io/gh/pboling/shiftable
+
+[code_triage]: https://www.codetriage.com/pboling/shiftable
+
+[depfu]: https://depfu.com/github/pboling/shiftable?project_id=32594
 
 [blogpage]: http://www.railsbling.com/tags/shiftable/
+
+[rubygems]: https://rubygems.org/gems/shiftable
+
+[chat]: https://gitter.im/pboling/shiftable?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+
+[maintenancee_policy]: https://guides.rubyonrails.org/maintenance_policy.html#security-issues
+
+[liberapay_donate]: https://liberapay.com/pboling/donate
+
+[gh_sponsors]: https://github.com/sponsors/pboling

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
 
@@ -61,11 +62,13 @@ module Shiftable
     # Creates anonymous Ruby Modules, containing dynamically built methods
     module ShiftCollectionModulizer
       def to_mod(signature)
+        prefix = signature.method_prefix
+        type = signature.type
         Module.new do
-          define_method(:"#{signature.mepr}shift_cx_column") do
-            signature.shift_column
+          define_method(:"#{prefix}shift_#{type}_column") do
+            signature.send("shift_#{type}_column")
           end
-          define_method(:"#{signature.mepr}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,13 +2,10 @@
 
 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
-    attr_accessor :associations, :options, :type
-    attr_reader :base
+    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
 
     # Imagine you are a Spaceship Captain, the Spaceship belongs_to you, and it has only one Captain.
     # But you have to sell it to your nemesis!
@@ -22,12 +19,29 @@ module Shiftable
     end
 
     def validate
-      raise ArgumentError, "type must be one of: #{VALID_TYPES}, provided: #{type}" unless VALID_TYPES.include?(type)
-      raise ArgumentError, "associations must be symbols" if associations.keys.detect { |a| !a.is_a?(Symbol) }
-      raise ArgumentError, "exactly two distinct associations must be provided" unless associations.keys.uniq.length == 2
+      raise ArgumentError, "type must be one of: #{VALID_TYPES}, provided: #{type}" if invalid_type?
+      raise ArgumentError, "associations must be symbols" if invalid_association_key_type?
+      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
+
+    def invalid_association_key_type?
+      associations.keys.detect { |key| !key.is_a?(Symbol) }
+    end
 
-      invalid_tokens = associations.keys - VALID_ASSOCIATIONS[type]
-      raise ArgumentError, "valid associations: #{VALID_ASSOCIATIONS[type]}, invalid: #{invalid_tokens}" if invalid_tokens.any?
+    def invalid_number_of_associations?
+      associations.keys.uniq.length != 2
     end
 
     # @note Chainable
@@ -42,84 +56,82 @@ 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
-
-      hr = bt.klass.reflect_on_association(has_rel)
-      raise ArgumentError, "Unable to find #{has_rel_name}: :#{has_rel} in #{bt.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
-
-      # returns nil or ActiveRecord::Relation object
-      def data_for_shift(id)
-        base.where(send("shift_column") => id) if super
+      def shift_data!(shift_to:, shift_from:)
+        validate_relationships
+        shifting_rel = ShiftingRelation.new(
+          to: shift_to,
+          from: shift_from,
+          column: shift_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
 
-      # returns false, nil or ActiveRecord::Relation object
-      def data_for_shift_safe(shift_to:, shift_from:)
-        return false unless super
-
-        data_for_shift(shift_from.id)
-      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 = data_for_shift_safe(shift_to: shift_to, shift_from: shift_from)
-        return false unless shifting_rel && shifting_rel.any?
-
-        shifting_rel.each do |shifting|
-          shifting.send("#{send(:shift_column)}=", shift_to.id)
+        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
-        before_shift&.call(shifting_rel: shifting_rel, shift_to: shift_to, shift_from: shift_from)
-        shifting_rel.each(&:save)
-        shifting_rel
       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 preflight_checks
-        options[:preflight_checks]
-      end
-
-      # returns nil or ActiveRecord object
-      def data_for_shift(id)
-        base.find_by(send("shift_column") => id) if super
-      end
-
-      # returns false, nil or ActiveRecord object
-      def data_for_shift_safe(shift_to:, shift_from:)
-        return false unless super
-
-        if preflight_checks
-          already_exists = shift_to.send(has_one)
-          return false if already_exists
-        end
-        data_for_shift(shift_from.id)
+      def precheck
+        options[:precheck]
       end
 
       def shift_data!(shift_to:, shift_from:)
         validate_relationships
-
-        shifting = data_for_shift_safe(shift_to: shift_to, shift_from: shift_from)
-        return false unless shifting
-
-        shifting.send("#{send(:shift_column)}=", shift_to.id)
-        shifting.save if before_shift.nil? || before_shift.call(shifting: shifting, shift_to: shift_to,
-                                                                shift_from: shift_from)
+        shifting = ShiftingRecord.new(
+          to: shift_to,
+          from: shift_from,
+          column: shift_column,
+          base: base
+        ) do
+          !precheck || !shift_to.send(has_rel)
+        end
+        shifting.shift do |result|
+          before_shift&.call(shifting: result, shift_to: shift_to, shift_from: shift_from)
+        end
       end
     end
 
@@ -134,12 +146,14 @@ module Shiftable
       options[:method_prefix]
     end
 
-    alias mepr method_prefix
-
     # will prevent the save if it returns false
     # allows for any custom logic to be run, such as setting shift_from attributes, prior to the shift is saved.
     def before_shift
-      options[:before_shift]
+      options[:before_shift] || DEFAULT_BEFORE_SHIFT
+    end
+
+    def shift_pcx_column
+      "#{polymorphic_as}_id"
     end
 
     def shift_column
@@ -147,18 +161,7 @@ module Shiftable
       reflection.foreign_key
     end
 
-    # Effect is to short-circuit data_for_shift method prior to executing the ActiveRecord query
-    #   if there is no ID, to avoid a full table scan when no id provided,
-    #   e.g. where(id: nil).
-    def data_for_shift(id)
-      true if id
-    end
-
-    # Effect is to short-circuit data_for_shift_safe method prior to executing the ActiveRecord query
-    #   if there is no ID, to avoid a full table scan when no id provided,
-    #   e.g. where(id: nil).
-    def data_for_shift_safe(shift_to:, shift_from:)
-      true if shift_from&.id && shift_to&.id
-    end
+    alias shift_sg_column shift_column
+    alias shift_cx_column shift_column
   end
 end

data/lib/shiftable/shifting.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Shiftable
+  # Gets data to be shifted
+  class Shifting
+    attr_reader :to, :from, :column, :base, :result, :run_save
+
+    def initialize(to:, from:, column:, base:)
+      @to = to
+      @from = from
+      @column = column
+      @base = base
+      validate
+      do_query = block_given? ? yield : true
+      @result = do_query ? query : nil
+      @run_save = true
+    end
+
+    # def found?
+    #   raise "found? must be defined in a subclass"
+    # end
+
+    # def shift
+    #   raise "shift must be defined in a subclass"
+    # end
+
+    private
+
+    def validate
+      raise ArgumentError, "shift_to must have an id (primary key) value, but is: #{to&.id}" unless to&.id
+      raise ArgumentError, "shift_from must have an id (primary key) value, but is: #{from&.id}" unless from&.id
+    end
+
+    # def query
+    #   raise "query must be defined in a subclass"
+    # end
+  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/shifting_record.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Shiftable
+  # Gets data to be shifted
+  class ShiftingRecord < Shifting
+    def found?
+      !!result
+    end
+
+    # @return true, false
+    def shift
+      return false unless found?
+
+      result.send("#{column}=", to.id)
+      @run_save = yield result if block_given?
+      result.save if run_save
+    end
+
+    private
+
+    def query
+      base.find_by(column => from.id)
+    end
+  end
+end

data/lib/shiftable/shifting_relation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Shiftable
+  # Gets data to be shifted
+  class ShiftingRelation < Shifting
+    include Enumerable
+
+    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("#{column}=", to.id)
+      end
+      @run_save = yield result if block_given?
+      each(&:save) if run_save
+      result
+    end
+
+    private
+
+    def query
+      base.where(column => from.id)
+    end
+  end
+end

data/lib/shiftable/single.rb

@@ -13,7 +13,7 @@
 #     extend Shiftable::Single.new(
 #             belongs_to: :captain,
 #             has_one: :spaceship,
-#             preflight_checks: true,
+#             precheck: true,
 #             before_shift: ->(shifting:, shift_to:, shift_from:) { shifting.ownership_changes += 1 }
 #           )
 #   end
@@ -21,7 +21,7 @@
 module Shiftable
   # Inheriting from Module is a powerful pattern. If you like it checkout the debug_logging gem!
   class Single < Module
-    def initialize(belongs_to:, has_one:, method_prefix: nil, preflight_checks: true, before_shift: nil)
+    def initialize(belongs_to:, has_one:, method_prefix: nil, precheck: true, before_shift: nil)
       # Ruby's Module initializer doesn't take any arguments
       super()
 
@@ -40,7 +40,7 @@ module Shiftable
         },
         options: {
           # Do not move record if a record already exists (we are shifting a "has_one" association, after all)
-          preflight_checks: preflight_checks,
+          precheck: precheck,
           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).
@@ -67,11 +67,12 @@ module Shiftable
     # Creates anonymous Ruby Modules, containing dynamically built methods
     module ShiftSingleModulizer
       def to_mod(signature)
+        prefix = signature.method_prefix
         Module.new do
-          define_method(:"#{signature.mepr}shift_column") do
-            signature.shift_column
+          define_method(:"#{prefix}shift_column") do
+            signature.send("shift_#{signature.type}_column")
           end
-          define_method(:"#{signature.mepr}shift_single") do |shift_to:, shift_from:|
+          define_method(:"#{prefix}shift_single") do |shift_to:, shift_from:|
             signature.shift_data!(shift_to: shift_to, shift_from: shift_from)
           end
         end

data/lib/shiftable/version.rb

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

data/lib/shiftable.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 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"
 require_relative "shiftable/single"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shiftable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Peter Boling
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-26 00:00:00.000000000 Z
+date: 2021-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -109,105 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.10'
 - !ruby/object:Gem::Dependency
-  name: rspec-block_is_expected
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: rubocop-faker
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-- !ruby/object:Gem::Dependency
-  name: rubocop-md
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.15'
-- !ruby/object:Gem::Dependency
-  name: rubocop-packaging
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.11'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.11'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
+  name: rspec-benchmark
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -221,21 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.6'
 - !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec-focused
+  name: rspec-block_is_expected
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -248,34 +136,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-thread_safety
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.21'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.21'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -314,11 +174,16 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - lib/shiftable.rb
 - 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
 - lib/shiftable/version.rb
 homepage: https://railsbling.com/tags/shiftable
@@ -336,14 +201,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.0.3.1
 signing_key:
 specification_version: 4
 summary: Easily shift record associations