New :fallback option to handle nil for singular associations

[cperezabo]

Hi folks, this PR adds a :fallback option to belongs_to, has_one, and embeds_one.

You hand it a Proc, and whenever the association would be nil, Mongoid returns whatever the Proc gives back (a null object).

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"

Works the same on has_one and embeds_one.

Things worth knowing:

• 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.

[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.