active_record-associated_object 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5816013890fc0f6868149661030643f47028edbb6a188d5014e7fd699e0138bd
-  data.tar.gz: ef0c4be8afb96727e5f379c988632ec44f0f77d105b8aadde944ac48362b7385
+  metadata.gz: 1876318d0052119a7e4080257d42bff11fee22385ac25a5d78023ce958d46fb9
+  data.tar.gz: d1089ada8474d59399331a71ec0815afd5a4a792191530fd273d25f0f328a916
 SHA512:
-  metadata.gz: 5f80f20322bf4661515fb6235c9d034e7ac68a22bc17e269971c8b2a1f5782affb28471316b65402bab66deedc9f63f322032fa216100c6966cd514c7421a100
-  data.tar.gz: 9def815025bf60d33b06ba6f7c9c185a59fca016f3e88a72d65fb64408dd0b4e7a34aea63c5a75de61004a64a80b86bd26e368ed021d105ed32bf6cca3a3f037
+  metadata.gz: f8200ebd8b229a4077af91fe9ab7b3af686de67c844a208cf843b8d828cb1d5a19fd65560bf4d911a02a67525f08541e31ad21d701fdb452f7a0113a01792cd3
+  data.tar.gz: d88d3a02dc2e9fbecef0a1060d1bdb35798ca8280ff860800e1c89219247b815e3ff16a7d7c5b0c193fa1474900b18aa96b23ce6ffe89c1c1adb68d135095f2d

data/Gemfile.lock

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

data/README.md

@@ -60,7 +60,7 @@ We've fixed this so you don't need to care, but this is what's happening.
 > `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`.
 
 > [!TIP]
-> You can pass multiple names too: `has_object :publisher, :classified, :fortification`. I recommend `-[i]er`, `-[i]ed` and `-ion` as the general naming conventions for your Associated Objects.
+> You can pass multiple names too: `has_object :seats, :entitlements, :publisher, :classified, :fortification`. I recommend `-s`, `-[i]er`, `-[i]ed` and `-ion` as the general naming conventions for your Associated Objects.
 
 > [!TIP]
 > Plural Associated Object names are also supported: `Account.has_object :seats` will look up `Account::Seats`.
@@ -87,6 +87,17 @@ end
 
 ### See Associated Objects in action
 
+#### RubyVideo.dev
+
+The team at https://www.rubyvideo.dev has been using Associated Objects to clarify the boundaries of their Active Records and collaborator Associated Objects.
+
+See the usage in the source here:
+
+- [`ActiveRecord::AssociatedObject` instances](https://github.com/search?q=repo%3Aadrienpoly%2Frubyvideo%20ActiveRecord%3A%3AAssociatedObject&type=code)
+- [`has_object` calls](https://github.com/search?q=repo%3Aadrienpoly%2Frubyvideo+has_object&type=code)
+
+#### Flipper
+
 The team at [Flipper](https://www.flippercloud.io) used Associated Objects to help keep their new billing structure clean.
 
 You can see real life examples in these blog posts:
@@ -140,7 +151,17 @@ end
 ### Extending the Active Record from within the Associated Object
 
 Since `has_object` eager-loads the Associated Object class, you can also move
-any integrating code into a provided `extension` block:
+any integrating code into the Associated Object.
+
+If you've got a few extensions, you can use `record` to access the Active Record class:
+
+```ruby
+class Post::Publisher < ActiveRecord::AssociatedObject
+  record.has_many :contracts, dependent: :destroy # `record` returns `Post` here.
+end
+```
+
+Alternatively, if you have many extensions, use the `extension` block:
 
 > [!NOTE]
 > Technically, `extension` is just `Post.class_eval` but with syntactic sugar.
@@ -220,7 +241,7 @@ Here's what [@nshki](https://github.com/nshki) found when they tried it:
 
 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
+### 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`.
 
@@ -240,6 +261,149 @@ class Post::PublisherTest < ActiveSupport::TestCase
 end
 ```
 
+### Active Model integration
+
+Associated Objects quack like `ActiveModel`s because we:
+
+- [`extend ActiveModel::Naming`](https://api.rubyonrails.org/classes/ActiveModel/Naming.html)
+- [`include ActiveModel::Conversion`](https://api.rubyonrails.org/classes/ActiveModel/Conversion.html)
+
+This means you can pass them to helpers like `form_with` and route helpers like `url_for` too.
+
+> [!NOTE]
+> We don't `include ActiveModel::Model` since we don't need `assign_attributes` and validations really.
+
+```ruby
+# app/controllers/post/publishers_controller.rb
+class Post::PublishersController < ApplicationController
+  before_action :set_publisher
+
+  def new
+  end
+
+  def create
+    @publisher.publish params.expect(publisher: :toast)
+    redirect_back_or_to root_url, notice: "Out it goes!"
+  end
+
+  private
+    def set_publisher
+      # Associated Objects are POROs, so behind the scenes we're really doing `Post.find(…).publisher`.
+      @publisher = Post::Publisher.find(params[:id])
+    end
+end
+```
+
+And then on the view side, you can pass it into `form_with`:
+
+```erb
+<%# app/views/post/publishers/new.html.erb %>
+<%# Here `form_with` calls `url_for(@publisher)` which calls `post_publisher_path(@publisher)`. %>
+<%= form_with model: @publisher do |form| %>
+  <%= form.text_field :toast %>
+  <%= form.submit "Publish with toast" %>
+<% end %>
+```
+
+Finally, the routing is pretty standard fare:
+
+```ruby
+namespace :post do
+  resources :publishers
+end
+```
+
+#### Rendering Associated Objects
+
+Associated Objects respond to `to_partial_path`, so you can pass them directly to `render`.
+
+We're using Rails' conventions here, so view paths look like this:
+
+```erb
+<%# With a Post::Publisher, this renders app/views/post/publishers/_publisher.html.erb %>
+<%= render publisher %>
+
+<%# With a Post::Comment::Rating, this renders app/views/post/comment/ratings/_rating.html.erb %>
+<%= render rating %>
+```
+
+We've also got full support for fragment caching, so this is possible:
+
+```erb
+<%# app/views/post/publishers/_publisher.html.erb %>
+<%= cache publisher do %>
+  <%# More publishing specific view logic. %>
+<% end %>
+```
+
+> [!NOTE]
+> We only support recyclable cache keys which has been the default since Rails 5.2.
+> This means the Active Record you associate with must have `SomeModel.cache_versioning = true` enabled.
+>
+> Associated Objects respond to `cache_key`, `cache_version` and `cache_key_with_version` like Active Records.
+
+### Polymorphic Associated Objects
+
+If you want to share logic between associated objects, you can do so via standard Ruby modules:
+
+```ruby
+# app/models/pricing.rb
+module Pricing
+  # If you need to share an `extension` across associated objects you can override `Module::included` like this:
+  def self.included(object) = object.extension do
+    # Add common integration methods onto `Account`/`User` when the module is included.
+    # See the `extension` block in the `Extending` section above for an example.
+  end
+
+  def price_set?
+    # Instead of referring to `account` or `user`, use the `record` method to target either.
+    record.price_cents.positive?
+  end
+end
+
+# app/models/account/pricing.rb
+class Account::Pricing < ActiveRecord::AssociatedObject
+  include ::Pricing
+end
+
+# app/models/user/pricing.rb
+class User::Pricing < ActiveRecord::AssociatedObject
+  include ::Pricing
+end
+```
+
+Now we can call `account.pricing.price_set?` & `user.pricing.price_set?`.
+
+> [!NOTE]
+> Polymorphic Associated Objects are definitely a more advanced topic,
+> so you need to know your Ruby module hierarchy and how to track what `self` changes to fairly well.
+
+#### Using `ActiveSupport::Concern` as an alternative
+
+If you prefer the look of Active Support concerns, here's the equivalent to the above Ruby module:
+
+```ruby
+# app/models/pricing.rb
+module Pricing
+  extend ActiveSupport::Concern
+
+  included do
+    extension do
+      # Add common integration methods onto `Account`/`User` when the concern is included.
+    end
+  end
+
+  def price_set?
+    # Instead of referring to `account` or `user`, use the `record` method to target either.
+    record.price_cents.positive?
+  end
+end
+```
+
+Active Support concerns have some extra features that standard Ruby modules don't, like support for deeply-nested concerns and `class_methods do`.
+
+In this case, if you're reaching for those, you're probably building something too intricate and potentially brittle.
+
 ### Active Job integration via GlobalID
 
 Associated Objects include `GlobalID::Identification` and have automatic Active Job serialization support that looks like this:

data/lib/active_record/associated_object/railtie.rb

@@ -6,14 +6,14 @@ class ActiveRecord::AssociatedObject::Railtie < Rails::Railtie
     end
   end
 
-  initializer "object_association.setup" do
-    ActiveSupport.on_load :active_job do
-      require "active_job/performs"
-      ActiveRecord::AssociatedObject.extend ActiveJob::Performs
-    rescue LoadError
-      # We haven't bundled active_job-performs, so we're continuing without it.
-    end
+  initializer "active_job.performs" do
+    require "active_job/performs"
+    ActiveRecord::AssociatedObject.extend ActiveJob::Performs if defined?(ActiveJob::Performs)
+  rescue LoadError
+    # We haven't bundled active_job-performs, so we're continuing without it.
+  end
 
+  initializer "object_association.setup" do
     ActiveSupport.on_load :active_record do
       require "active_record/associated_object/object_association"
       include ActiveRecord::AssociatedObject::ObjectAssociation

data/lib/active_record/associated_object/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   class AssociatedObject
-    VERSION = "0.8.2"
+    VERSION = "0.9.0"
   end
 end

data/lib/active_record/associated_object.rb

@@ -1,38 +1,63 @@
+# frozen_string_literal: true
+
 class ActiveRecord::AssociatedObject
+  extend ActiveModel::Naming
+  include ActiveModel::Conversion
+
   class << self
-    def inherited(klass)
-      record_klass   = klass.module_parent
-      record_name    = klass.module_parent_name.demodulize.underscore
-      attribute_name = klass.to_s.demodulize.underscore.to_sym
+    def inherited(new_object)
+      new_object.associated_via(new_object.module_parent)
+    end
 
-      unless record_klass.respond_to?(:descends_from_active_record?) && record_klass.descends_from_active_record?
-        raise ArgumentError, "#{record_klass} isn't valid; can only associate with ActiveRecord::Base subclasses"
+    def associated_via(record)
+      unless record.respond_to?(:descends_from_active_record?) && record.descends_from_active_record?
+        raise ArgumentError, "#{record} isn't a valid namespace; can only associate with ActiveRecord::Base subclasses"
       end
 
-      klass.alias_method record_name, :record
-      klass.define_singleton_method(:record_klass)   { record_klass }
-      klass.define_singleton_method(:attribute_name) { attribute_name }
-      klass.delegate :record_klass, :attribute_name, to: :class
+      @record, @attribute_name = record, model_name.element.to_sym
+      alias_method record.model_name.element, :record
     end
 
+    attr_reader :record, :attribute_name
+    delegate :primary_key, :unscoped, :transaction, to: :record
+
     def extension(&block)
-      record_klass.class_eval(&block)
+      record.class_eval(&block)
     end
 
-    def respond_to_missing?(...) = record_klass.respond_to?(...) || super
-    delegate :unscoped, :transaction, :primary_key, to: :record_klass
-
     def method_missing(method, ...)
-      if !record_klass.respond_to?(method) then super else
-        record_klass.public_send(method, ...).then do |value|
+      if !record.respond_to?(method) then super else
+        record.public_send(method, ...).then do |value|
           value.respond_to?(:each) ? value.map(&attribute_name) : value&.public_send(attribute_name)
         end
       end
     end
+    def respond_to_missing?(...) = record.respond_to?(...) || super
+  end
+
+  module Caching
+    def cache_key_with_version
+      "#{cache_key}-#{cache_version}".tap { _1.delete_suffix!("-") }
+    end
+    delegate :cache_version, to: :record
+
+    def cache_key
+      case
+      when !record.cache_versioning?
+        raise "ActiveRecord::AssociatedObject#cache_key only supports #{record_klass}.cache_versioning = true"
+      when new_record?
+        "#{model_name.cache_key}/new"
+      else
+        "#{model_name.cache_key}/#{id}"
+      end
+    end
   end
+  include Caching
 
   attr_reader :record
-  delegate :id, :transaction, to: :record
+  delegate :id, :new_record?, :persisted?, to: :record
+  delegate :updated_at, :updated_on, to: :record # Helpful when passing to `fresh_when`/`stale?`
+  delegate :transaction, to: :record
 
   def initialize(record)
     @record = record

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_record-associated_object
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2025-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord