New :fallback option to handle nil for singular associations

[cperezabo]

Summary

A :fallback option has been added to belongs_to, has_one, and embeds_one.

This option accepts a Proc, and whenever the association would be nil, Mongoid returns whatever the proc gives back (i.e. it follows the "null object" pattern).

class Anonymous
  def attribution
    "Composer unknown"
  end
end

class Composer
  include Mongoid::Document
  field :name

  def attribution
    "Composed by #{name}"
  end
end

class Symphony
  include Mongoid::Document
  belongs_to :composer, fallback: -> { Anonymous.new }
end

Symphony.create!.composer.attribution
# => "Composer unknown"

Symphony.create!(composer: Composer.create!(name: "Mahler")).composer.attribution
# => "Composed by Mahler"

It behaves similarly with has_one and embeds_one.

Things to note:

• The proc runs on every access — fresh instance each time. If you want identity, memoize in the Proc.
• Null object never persists. Anything you assign that isn't an instance of the association's class (or a subclass) becomes nil — whether via setter or constructor.
• A real document always wins — if the FK is set, the Proc never runs.
• Can't combine with :autobuild (they want opposite things). Raises InvalidRelationOption.

Credit to @cperezabo for this feature.

[davidfabbretti]

Wow! Nice feature! 🚀

[jamis]

@cperezabo thank you for this PR -- it looks like a convenient feature.

However, there are some subtle potential side-effects that I'm a bit worried about:

• Associations with dependent: set may cause problems. If you look at any of the _dependent_* helper methods (in association/depending.rb, you'll see they call send(association.name) with no without_autobuild wrapper. This leaves them vulnerable to returning the fallback object, if one is defined---which could result in NoMethodError being raised when destroy or nullify (etc.) is called on that fallback.
• Relying on association.relation_class is a bit fraught. If you look at the comment in Relatable#relation_class, you'll see calling this method on a polymorphic association will generally fail with a NameError or produce misleading results. Polymorphic associations may need to be treated specially in the guard you added in define_setter!.
• Nested attributes (specifically in association/nested/one.rb) call parent.send(association.name), which may return the fallback object. Looking in the build method in that file, there are multiple opportunities for NoMethodError exceptions to be raised when processing a nested attribute update.

[jamis]

InvalidRelationOption is mostly intended for reporting an option that is not recognized. It might be better to simply raise ArgumentError here? Because the message with this exception won't say anything about :autobuild being invalid when :fallback is specified, which is the actual issue here.

[cperezabo]

Hi @jamis, I've addressed each of your points. I also scanned the repository with Claude to look for any other spots with the same problem, and it found two — I've added tests for those as well. There's a commit per point so they're easy to review. You can squash the branch or leave it as is; I don't mind either way!

Just to clarify, I always follow the TDD approach, so the tests were added one by one, along with the production code.

[jamis]

Thank you! This looks really good 👍

[cperezabo]

Thanks @jamis, regarding the documentation, I visited https://github.com/mongodb/docs-mongoid to make the changes. However, it states that the documentation is now internally managed. Is there any way for me to contribute?

[jamis]

...the documentation is now internally managed. Is there any way for me to contribute?

Thank you so much for being willing to contribute documentation! Your PR description was wonderfully descriptive, and I'll include it in the release notes for the next version (I made a few tweaks to make it appropriate for that audience). As for the docs at https://www.mongodb.com/docs -- those are all internally managed to maintain a consistent voice and presentation across all the different driver languages that we support. I don't even have direct access to those docs; it's managed by a separate documentation team. However, if there is anything specific you'd like highlighted in the docs (which do not need to be in the release notes), feel free to edit the PR description and add another header at the same level as the "Summary" header; I'll point the docs team at this PR when they ask how to document the feature.

(The "Summary" header and its associated contents are used to build our release notes.)