MONGOID-5057 Add support for has_many :through

[jamis]

Summary

Implements read-only :through associations for has_one and has_many, matching ActiveRecord's API:

class Customer
  has_one :franchise
  has_one :store, through: :franchise
end

class Physician
  has_many :appointments
  has_many :patients, through: :appointments
end

Both association types support :source to override the inferred source name, and :class_name for non-conventional class names. has_many :through additionally accepts :order. All through associations are read-only; write attempts raise Mongoid::Errors::ReadonlyAssociation. Eager loading via includes is supported for both types.

The two query patterns supported for has_many :through are the join-model pattern (FK on the intermediate, e.g. belongs_to :patient on Appointment) and the reverse-FK pattern (FK on the target, e.g. has_many :readers on Book).

Out of Scope

• write operations
• polymorphic through associations
• custom :scope
• embedded through associations
• chaining through a has_many :through that is itself a through association
• has_and_belongs_to_many as the source association.

[Copilot]

Pull request overview

This PR adds read-only :through support to Mongoid referenced associations, enabling has_one :through and has_many :through with includes preloading support and a dedicated Mongoid::Errors::ReadonlyAssociation error for mutation attempts.

Changes:

• Introduces new association metadata/proxy/eager-loader implementations for Referenced::HasOneThrough and Referenced::HasManyThrough.
• Extends association macro dispatch to select *_through association types when through: is provided.
• Adds a localized ReadonlyAssociation error and updates eager loading behavior to fall back from $lookup when through associations are included.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
spec/mongoid/errors/readonly_association_spec.rb	Adds specs for the new ReadonlyAssociation error messaging.
spec/mongoid/association/referenced/has_one_through/proxy_spec.rb	Tests has_one-through proxy behavior and eager loader selection.
spec/mongoid/association/referenced/has_one_through/eager_spec.rb	Verifies includes-based preloading for has_one-through.
spec/mongoid/association/referenced/has_one_through_spec.rb	Adds unit + integration coverage for has_one-through metadata and read-only setter.
spec/mongoid/association/referenced/has_many_through/proxy_spec.rb	Tests has_many-through proxy read/mutation API surface.
spec/mongoid/association/referenced/has_many_through/eager_spec.rb	Verifies includes-based preloading for has_many-through.
spec/mongoid/association/referenced/has_many_through_spec.rb	Adds unit + integration coverage for has_many-through metadata, ordering, and patterns.
spec/mongoid/association/macros_spec.rb	Ensures macros instantiate the correct *_through metadata when through: is present.
spec/mongoid/association/eager_loadable_spec.rb	Confirms eager_load warns and falls back to preload for through associations.
lib/mongoid/errors/readonly_association.rb	Implements new error class used for write attempts on through associations.
lib/mongoid/errors.rb	Requires the new error class.
lib/mongoid/association/referenced/has_one_through/proxy.rb	Adds proxy class for has_one-through association type.
lib/mongoid/association/referenced/has_one_through/eager.rb	Adds two-query preloader for has_one-through.
lib/mongoid/association/referenced/has_one_through.rb	Adds metadata/definition logic for has_one-through.
lib/mongoid/association/referenced/has_many_through/proxy.rb	Adds read-only proxy wrapper for has_many-through criteria.
lib/mongoid/association/referenced/has_many_through/eager.rb	Adds two-query preloader for has_many-through.
lib/mongoid/association/referenced/has_many_through.rb	Adds metadata/definition logic for has_many-through criteria building and ids getter.
lib/mongoid/association/referenced.rb	Requires the new through association implementations.
lib/mongoid/association/macros.rb	Routes has_one/has_many to through-metadata when through: is provided.
lib/mongoid/association/eager_loadable.rb	Detects through inclusions and falls back from $lookup eager loading with a warning.
lib/mongoid/association.rb	Adds internal THROUGH_MACRO_MAPPING for has_one/has_many.
lib/config/locales/en.yml	Adds i18n strings for the new readonly_association error.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sandstrom]

I was wondering just now, does mongoid support this -- lo and behold! :)

Two small questions:

• Are there any docs for this yet? Did find them in the diff, but maybe it's coming later or is in another repo?

• Will the docs elaborate on query performance implications, because I'm guessing the underlying queries will either be more expensive than what you'd usually have in a SQL database, or need to use aggregation-queries?

[jamis]

There will be docs, but we have a separate documentation team and they use an internal repository. There is nothing available yet.

The docs will probably not going into great depth on performance implications for this feature; the current implementation is fairly naive, though, and optimized more for convenience than performance right now. This is minimal "v1". There is definitely more that could be done, both for performance optimization, and for extending what is supported.

[sandstrom]

Great! 🎉

Not trying to be annoying about performance. I think this is a great start.

As long as the docs just explains what queries will be made underr the hood, the reader can deduce what that means for them in terms of perf.