active_record-associated_object 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b973496c3658defdee08fb40292bad58fadbc743a732cface722c40f8b8152c
-  data.tar.gz: c6a3758599c0f5ce22470c18c23c958ebf05827a7f52ae0d07507cbd4b8b6346
+  metadata.gz: ca7c634684913b4f2f55b96e54036df0590fe963e06beb15bf98a641a450c5e1
+  data.tar.gz: 279780001730e8d339d15dfa3f6659be157169d74a1e4949132c5d7a2b8e596a
 SHA512:
-  metadata.gz: 57db29d169ee310087c539e1eb64ccce3bdeb6a98bdb7532723db4f90656140d521c9925efb3aa17782cd84b3e1906dfaaf0cd6dd72d69ad54e90b159a423547
-  data.tar.gz: dca66954be7f3e84ea76010e7714366532c506eb3ab02c1174bd47122ecce0af5223656ee11ed425d962d86b5a443ce69b95a187d40318ff555f497103df88ff
+  metadata.gz: e4b86186ef2aa86f31535313a22adf2835694829ba3a53c3d6b5847429ab5a002c3e09f36e3718f756370ca12f3d335b7851b42a8939d234f8de00d71970e255
+  data.tar.gz: ff2ac40c52831018085167aa42f9212b4cecdd7cb5dac199d9f258278553752b7cf3b40df2295d240df65bd6cc685981dd82d710b947d32b8192b5b8d39ee3eb

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    active_record-associated_object (0.5.2)
+    active_record-associated_object (0.6.0)
       activerecord (>= 6.1)
 
 GEM

data/README.md

@@ -1,81 +1,180 @@
 # ActiveRecord::AssociatedObject
 
-Associate a Ruby PORO with an Active Record class and have it quack like one. Build and extend your domain model relying on the Active Record association to make it unique.
+Rails applications can end up with models that get way too big, and so far, the
+Ruby community response has been Service Objects. But sometimes `app/services`
+can turn into another junk drawer that doesn't help you build and make concepts for your Domain Model.
 
-## Usage
+`ActiveRecord::AssociatedObject` takes that head on. Associated Objects are a new domain concept, a context object, that's meant to
+help you tease out collaborator objects for your Active Record models.
+
+They're essentially POROs that you associate with an Active Record model to get benefits both in simpler code as well as automatic `app/models` organization.
+
+Let's look at an example. Say you have a `Post` model that encapsulates a blog post in a Content-Management-System:
 
 ```ruby
-# app/models/post.rb
-class Post < ActiveRecord::Base
-  # `has_object` defines a `publisher` method that calls Post::Publisher.new(post).
-  has_object :publisher
+class Post < ApplicationRecord
 end
+```
+
+You've identified that several things need to happen when a post gets published.
+But where does that behavior live; in `Post`? That might get messy.
+
+If we put it in a classic Service Object, we've got access to a `def call` method and that's it — what if we need other methods that operate on the state? And then having `PublishPost` or a similar ad-hoc name in `app/services` can pollute that folder over time.
+
+What if we instead identified a `Publisher` collaborator object, a Ruby class that handles publishing? What if we required it to be placed within `Post::` to automatically help connote the object as belonging to and collaborating with `Post`? Then we'd get `app/models/post/publisher.rb` which guides naming and gives more organization in your app automatically through that convention — and helps prevent a junk drawer from forming.
 
+This is what Associated Objects are! We'd define it like this:
+
+```ruby
 # app/models/post/publisher.rb
-class Post::Publisher
-  def initialize(post)
-    @post = post
-  end
+class Post::Publisher < ActiveRecord::AssociatedObject
 end
 ```
 
-If you want Active Job, GlobalID and Kredis integration you can also have `Post::Publisher` inherit from `ActiveRecord::AssociatedObject`. This extends the standard PORO with details from the `Post::` namespace and the post primary key.
+And then you can declare it in `Post`:
 
 ```ruby
-# app/models/post/publisher.rb
-class Post::Publisher < ActiveRecord::AssociatedObject
-  # ActiveRecord::AssociatedObject defines initialize(post) automatically. It's derived from the `Post::` namespace.
+# app/models/post.rb
+class Post < ApplicationRecord
+  has_object :publisher
+end
+```
 
-  kredis_datetime :publish_at # Kredis integration generates a "post:publishers:<post_id>:publish_at" key.
+There isn't anything super special happening yet. Here's essentially what's happening under the hood:
 
-  # `performs` builds a `Post::Publisher::PublishJob` and routes configs over to it.
-  performs :publish, queue_as: :important, discard_on: SomeError do
-    retry_on TimeoutError, wait: :exponentially_longer
-  end
+```ruby
+class Post::Publisher
+  attr_reader :post
+  def initialize(post) = @post = post
+end
+
+class Post < ApplicationRecord
+  def publisher = @publisher ||= Post::Publisher.new(self)
+end
+```
+
+> [!TIP]
+> `has_object` only requires a namespace and an initializer that takes a single argument. The above `Post::Publisher` is perfectly valid as an Associated Object — same goes for `class Post::Publisher < Data.define(:post); end`.
+
+See how we're always expecting a link to the model, here `post`?
 
+Because of that, you can rely on `post` from the associated object:
+
+```ruby
+class Post::Publisher < ActiveRecord::AssociatedObject
   def publish
     # `transaction` is syntactic sugar for `post.transaction` here.
     transaction do
-      # A `post` method is generated to access the associated post. There's also a `record` alias available.
       post.update! published: true
       post.subscribers.post_published post
+
+      # There's also a `record` alias available if you prefer the more general reading version:
+      # record.update! published: true
+      # record.subscribers.post_published record
     end
   end
 end
 ```
 
-### Namespaced models
+### Forwarding callbacks onto the associated object
 
-If you have a namespaced Active Record like this:
+To further help illustrate how your collaborator Associated Objects interact with your domain model, you can forward callbacks.
+
+Say we wanted to have our `publisher` automatically publish posts after they're created. Or we need to refresh a publishing after a post has been touched. Or what if we don't want posts to be destroyed if they're published due to HAHA BUSINESS rules?
+
+So `has_object` can state this and forward those callbacks onto the Associated Object:
 
 ```ruby
-# app/models/post/comment.rb
-class Post::Comment < ApplicationRecord
-  belongs_to :post
+class Post < ActiveRecord::Base
+  # Passing `true`
+  has_object :publisher, after_create_commit: :publish,
+    after_touch: true, before_destroy: :prevent_errant_post_destroy
 
-  has_object :rating
+  # The above is the same as writing:
+  after_create_commit { publisher.publish }
+  after_touch { publisher.after_touch }
+  before_destroy { publisher.prevent_errant_post_destroy }
+end
+
+class Post::Publisher < ActiveRecord::AssociatedObject
+  def publish
+  end
+
+  def after_touch
+    # Respond to the after_touch on the Post.
+  end
+
+  def prevent_errant_post_destroy
+    # Passed callbacks can throw :abort too, and in this example prevent post.destroy.
+    throw :abort if haha_business?
+  end
 end
 ```
 
-You can define the associated object in the same way it was done for `Post::Publisher` above, within the `Post::Comment` namespace:
+### Primary Benefit: Organization through Convention
+
+The primary benefit for right now is that by focusing the concept of namespaced Collaborator Objects through Associated Objects, you will start seeing them when you're modelling new features and it'll change how you structure and write your apps.
+
+This is what [@natematykiewicz](https://github.com/natematykiewicz) found when they started using the gem (we'll get to `ActiveJob::Performs` soon):
+
+> We're running `ActiveRecord::AssociatedObject` and `ActiveJob::Performs` (via the associated object) in 3 spots in production so far. It massively improved how I was architecting a new feature. I put a PR up for review and a coworker loved how organized and easy to follow the large PR was because of those 2 gems. I'm now working on another PR in our app where I'm using them again. I keep seeing use-cases for them now. I love it. Thank you for these gems!
+>
+> Anyone reading this, if you haven't checked them out yet, I highly recommend it.
+
+And about a month later it was still holding up:
+
+> Just checking in to say we've added like another 4 associated objects to production since my last message. `ActiveRecord::AssociatedObject` + `ActiveJob::Performs` is like a 1-2 punch super power. I'm a bit surprised that this isn't Rails core to be honest. I want to migrate so much of our code over to this. It feels much more organized and sane. Then my app/jobs folder won't have much in it because most jobs will actually be via some associated object's _later method. app/jobs will then basically be cron-type things (deactivate any expired subscriptions).
+
+Let's look at testing, then we'll get to passing these POROs to jobs like the quotes mentioned!
+
+### A Quick Aside: Testing Associated Objects
+
+Follow the `app/models/post.rb` and `app/models/post/publisher.rb` naming structure in your tests and add `test/models/post/publisher_test.rb`.
+
+Then test it like any other object:
 
 ```ruby
-# app/models/post/comment/rating.rb
-class Post::Comment::Rating < ActiveRecord::AssociatedObject
-  def great?
-    # A `comment` method is generated to access the associated comment. There's also a `record` alias available.
-    comment.author.subscriber_of? comment.post.author
+# test/models/post/publisher_test.rb
+class Post::PublisherTest < ActiveSupport::TestCase
+  # You can use Fixtures/FactoryBot to get a `post` and then extract its `publisher`:
+  setup { @publisher = posts(:one).publisher }
+  setup { @publisher = FactoryBot.build(:post).publisher }
+
+  test "publish updates the post" do
+    @publisher.publish
+    assert @publisher.post.reload.published?
   end
 end
 ```
 
-### Composite primary keys
+### Active Job integration via GlobalID
 
-We support Active Record models with composite primary keys out of the box.
+Associated Objects include `GlobalID::Identification` and have automatic Active Job serialization support that looks like this:
 
-Just setup the associated objects like the above examples and you've got GlobalID/Active Job and Kredis support automatically.
+```ruby
+class Post::Publisher < ActiveRecord::AssociatedObject
+  class PublishJob < ApplicationJob
+    def perform(publisher) = publisher.publish
+  end
+
+  def publish_later
+    PublishJob.perform_later self # We're passing this PORO to the job!
+  end
+
+  def publish
+    # …
+  end
+end
+```
 
-### Remove Active Job boilerplate with `performs`
+> [!NOTE]
+> Internally, Active Job serializes Active Records as GlobalIDs. Active Record also includes `GlobalID::Identification`, which requires the `find` and `where(id:)` class methods.
+>
+> We've added `Post::Publisher.find` & `Post::Publisher.where(id:)` that calls `Post.find(id).publisher` and `Post.where(id:).map(&:publisher)` respectively.
+
+This pattern of a job `perform` consisting of calling an instance method on a sole domain object is ripe for a convention, here's how to do that.
+
+#### Remove Active Job boilerplate with `performs`
 
 If you also bundle [`active_job-performs`](https://github.com/kaspth/active_job-performs) in your Gemfile like this:
 
@@ -84,7 +183,7 @@ gem "active_job-performs"
 gem "active_record-associated_object"
 ```
 
-Every associated object now has access to the `performs` macro, so you can do this:
+Every Associated Object (and Active Records too) now has access to the `performs` macro, so you can do this:
 
 ```ruby
 class Post::Publisher < ActiveRecord::AssociatedObject
@@ -100,7 +199,7 @@ class Post::Publisher < ActiveRecord::AssociatedObject
 end
 ```
 
-which is equivalent to this:
+which spares you writing all this:
 
 ```ruby
 class Post::Publisher < ActiveRecord::AssociatedObject
@@ -111,56 +210,74 @@ class Post::Publisher < ActiveRecord::AssociatedObject
 
   # Individual method jobs inherit from the `Post::Publisher::Job` defined above.
   class PublishJob < Job
-    def perform(publisher, *arguments, **options)
-      # GlobalID integration means associated objects can be passed into jobs like Active Records, i.e. we don't have to do `post.publisher`.
-      publisher.publish(*arguments, **options)
-    end
+    # Here's the GlobalID integration again, i.e. we don't have to do `post.publisher`.
+    def perform(publisher, *, **) = publisher.publish(*, **)
   end
 
   class RetractJob < Job
-    def perform(publisher, *arguments, **options)
-      publisher.retract(*arguments, **options)
-    end
+    def perform(publisher, *, **) = publisher.retract(*, **)
   end
 
-  def publish_later(*arguments, **options)
-    PublishJob.perform_later(self, *arguments, **options)
-  end
+  def publish_later(*, **) = PublishJob.perform_later(self, *, **)
+  def retract_later(*, **) = RetractJob.perform_later(self, *, **)
+end
+```
 
-  def retract_later(*arguments, **options)
-    RetractJob.perform_later(self, *arguments, **options)
-  end
+Note: you can also pass more complex configuration like this:
+
+```ruby
+performs :publish, queue_as: :important, discard_on: SomeError do
+  retry_on TimeoutError, wait: :exponentially_longer
 end
 ```
 
 See the `ActiveJob::Performs` README for more details.
 
-### Passing callbacks onto the associated object
+### Namespaced models
 
-`has_object` accepts a hash of callbacks to pass.
+If you have a namespaced Active Record like this:
 
 ```ruby
-class Post < ActiveRecord::Base
-  # Callbacks can be passed too to a specific method.
-  has_object :publisher, after_touch: true, before_destroy: :prevent_errant_post_destroy
+# app/models/post/comment.rb
+class Post::Comment < ApplicationRecord
+  belongs_to :post
+  belongs_to :creator, class_name: "User"
 
-  # The above is the same as writing:
-  after_touch { publisher.after_touch }
-  before_destroy { publisher.prevent_errant_post_destroy }
+  has_object :rating
 end
+```
 
-class Post::Publisher < ActiveRecord::AssociatedObject
-  def after_touch
-    # Respond to the after_touch on the Post.
+You can define the associated object in the same way it was done for `Post::Publisher` above, within the `Post::Comment` namespace:
+
+```ruby
+# app/models/post/comment/rating.rb
+class Post::Comment::Rating < ActiveRecord::AssociatedObject
+  def good?
+    # A `comment` method is generated to access the associated comment. There's also a `record` alias available.
+    comment.creator.subscriber_of? comment.post.creator
   end
+end
+```
 
-  def prevent_errant_post_destroy
-    # Passed callbacks can throw :abort too, and in this example prevent post.destroy.
-    throw :abort if haha_business?
+And then test it in `test/models/post/comment/rating_test.rb`:
+
+```ruby
+class Post::Comment::RatingTest < ActiveSupport::TestCase
+  setup { @rating = posts(:one).comments.first.rating }
+  setup { @rating = FactoryBot.build(:post_comment).rating }
+
+  test "pretty, pretty, pretty, pretty good" do
+    assert @rating.good?
   end
 end
 ```
 
+### Composite primary keys
+
+We support Active Record models with composite primary keys out of the box.
+
+Just setup the associated objects like the above examples and you've got GlobalID/Active Job and Kredis support automatically.
+
 ## Risks of depending on this gem
 
 This gem is relatively tiny and I'm not expecting more significant changes on it, for right now. It's unofficial and not affiliated with Rails core.

data/active_record-associated_object.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary  = "Associate a Ruby PORO with an Active Record class and have it quack like one."
   spec.homepage = "https://github.com/kaspth/active_record-associated_object"
   spec.license  = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

data/lib/active_record/associated_object/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   class AssociatedObject
-    VERSION = "0.5.2"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_record-associated_object
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-13 00:00:00.000000000 Z
+date: 2023-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -58,14 +58,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: Associate a Ruby PORO with an Active Record class and have it quack like