errgonomic 0.8.3 → 0.9.0

data/lib/errgonomic/option.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+require 'set'
+require 'stringio'
+
 module Errgonomic
   module Option
     # The base class for all options. Some and None are subclasses.
     #
+    # An Option is an object, so it is always truthy. A None does not stand
+    # in for nil in a conditional, and `||` hands back the wrapper rather
+    # than the fallback. Reach for a combinator to get at the inner value.
+    #
     class Any
       include Comparable
 
@@ -16,6 +23,11 @@ module Errgonomic
         is_none_or: :none_or?
       }.freeze
 
+      # Names already nudged about. A soft deprecation is a message to a
+      # developer, and one per process says it; one per call turns a hot
+      # path into a stderr flood.
+      NUDGED = Set.new
+
       # An Option deliberately forwards nothing to its inner value, so a miss
       # here is almost always someone treating the container as its contents.
       # Teach the route out instead of leaving a bare NoMethodError. Rust
@@ -72,7 +84,44 @@ module Errgonomic
       #   None() == None() # => true
       #   Some(1) == 1 # => false
       #   None() == nil # => false
+      #
+      # @example strict equality makes a cross-type comparison an error
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Some(5) == 5
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.class
+      #     end
+      #   end # => Errgonomic::TypeMismatchError
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Some(5) != 5
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.message.include?("!=")
+      #     end
+      #   end # => true
+      #   Errgonomic.with_strict_equality { Some(5) == Some(5) } # => true
+      #   Errgonomic.with_strict_equality { Some(5) == None() } # => false
+      #
+      # @example a Result is another container, not another Option
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Some(1) == Ok(1)
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.message.include?("different containers")
+      #     end
+      #   end # => true
+      #
+      # @example nil is another type, and absence here is the discriminant
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       None() == nil
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.message.include?("none?")
+      #     end
+      #   end # => true
       def ==(other)
+        strict_equality!(other, '==')
         return false if self.class != other.class
         return true if none?
 
@@ -90,7 +139,25 @@ module Errgonomic
       #   None().eql?(None()) # => true
       #   { Some(5) => 1 }[Some(5)] # => 1
       #   [Some(1), Some(1), None(), None()].uniq # => [Some(1), None()]
+      #
+      # @example strict equality reaches eql?, and leaves hash alone
+      #   Errgonomic.with_strict_equality do
+      #     begin
+      #       Some(5).eql?(5)
+      #     rescue Errgonomic::TypeMismatchError => e
+      #       e.class
+      #     end
+      #   end # => Errgonomic::TypeMismatchError
+      #   Errgonomic.with_strict_equality { Some(5).hash == Some(5).hash } # => true
+      # Ruby derives != from ==, so a strict-equality message would name the
+      # operator the caller did not write.
+      def !=(other)
+        strict_equality!(other, '!=')
+        super
+      end
+
       def eql?(other)
+        strict_equality!(other, 'eql?')
         return false if self.class != other.class
         return true if none?
 
@@ -124,9 +191,11 @@ module Errgonomic
       end
 
       # Options order like Rust's: None sorts before any Some, and Somes
-      # order by their inner values. Follows Ruby's <=> convention of
-      # returning nil for incomparable operands, whether the other object is
-      # not an Option or the inner values do not themselves compare.
+      # order by their inner values. Two Options whose inner values do not
+      # themselves compare follow Ruby's convention and answer nil. A
+      # non-Option operand raises instead: Comparable turns a nil here into
+      # an ArgumentError that names the Option as the operand at fault, where
+      # what went wrong is that a wrapper was ordered against a bare value.
       #
       # @example
       #   (Some(5) <=> Some(6)) # => -1
@@ -134,11 +203,20 @@ module Errgonomic
       #   (Some(5) <=> None()) # => 1
       #   (None() <=> None()) # => 0
       #   (Some(1) <=> Some("x")) # => nil
-      #   (Some(1) <=> 1) # => nil
       #   [Some(2), None(), Some(1)].sort # => [None(), Some(1), Some(2)]
       #   [Some(2), Some(1)].min # => Some(1)
+      #
+      # @example a bare value is not ordered against an Option
+      #   Some(5) <= 6 # => raise Errgonomic::TypeMismatchError, "cannot compare Some(5) with Integer; test the inner value (some_and? { |v| v <= other }) or reach for it (map, unwrap_or)"
+      #   Some(5).some_and? { |v| v <= 6 } # => true
+      #   Some(5).map { |v| v <= 6 } # => Some(true)
       def <=>(other)
-        return nil unless other.is_a?(Errgonomic::Option::Any)
+        unless other.is_a?(Errgonomic::Option::Any)
+          raise Errgonomic::TypeMismatchError,
+                "cannot compare #{inspect} with #{other.class}; test the inner value " \
+                '(some_and? { |v| v <= other }) or reach for it (map, unwrap_or)'
+        end
+
         return none? ? 0 : 1 if other.none?
         return -1 if none?
 
@@ -197,13 +275,15 @@ module Errgonomic
       # The presence helpers on Object keep their receiver; on an Option that
       # would hand back the wrapper where the caller asked for a value. Here
       # the present side unwraps instead, so a name that reads like an
-      # accessor behaves like one. The whole family is soft-deprecated on
-      # Options in favor of the combinators, so each call nudges via stderr,
-      # and the blank side, which has no working call sites to preserve,
-      # teaches rather than guesses at semantics.
+      # accessor behaves like one. The +_or+ spellings are soft-deprecated on
+      # Options in favor of the combinators and nudge via stderr; `presence`
+      # is the Rails idiom for unwrap_or(nil) and stays. The blank side, which
+      # has no working call sites to preserve, teaches rather than guesses at
+      # semantics.
 
       # Returns the inner value of a Some, and raises on a None. Presence
-      # follows the discriminant, so Some(nil) yields nil.
+      # follows the discriminant, so Some(nil) yields nil. A block is called
+      # only on the None branch, as it is for expect!.
       #
       # @param message [String] The error message to raise on a None.
       # @return [Object] The inner value of a Some.
@@ -212,9 +292,10 @@ module Errgonomic
       #   Some("secret").present_or_raise!("no secret") # => "secret"
       #   Some(nil).present_or_raise!("no secret") # => nil
       #   None().present_or_raise!("no secret") # => raise Errgonomic::NotPresentError, "no secret"
-      def present_or_raise!(message)
-        presence_nudge('present_or_raise', 'expect!')
-        raise Errgonomic::NotPresentError, message if none?
+      #   None().present_or_raise! { "no secret for #{7}" } # => raise Errgonomic::NotPresentError, "no secret for 7"
+      def present_or_raise!(message = nil, &block)
+        presence_nudge('present_or_raise!', 'expect!')
+        raise Errgonomic::NotPresentError, block ? block.call : message if none?
 
         value
       end
@@ -231,6 +312,18 @@ module Errgonomic
       # @example
       #   Some("secret").present_or("fallback") # => "secret"
       #   None().present_or("fallback") # => "fallback"
+      #
+      # @example the nudge fires once per process, so a hot path stays quiet
+      #   Some(1).present_or(2)
+      #   nudges = StringIO.new
+      #   original = $stderr
+      #   begin
+      #     $stderr = nudges
+      #     Some(1).present_or(2)
+      #   ensure
+      #     $stderr = original
+      #   end
+      #   nudges.string # => ""
       def present_or(default)
         presence_nudge('present_or', 'unwrap_or')
         return default if none?
@@ -256,15 +349,30 @@ module Errgonomic
 
       # Returns the inner value of a Some, and nil on a None, so the Rails
       # +presence || default+ idiom reaches the value rather than the wrapper.
+      # Presence follows the discriminant, so a blank inner value is still a
+      # value: Some("").presence is "", where Object#presence answers nil.
       #
       # @return [Object, nil] The inner value of a Some, otherwise nil.
       #
       # @example
       #   Some("secret").presence # => "secret"
+      #   Some("").presence # => ""
       #   None().presence # => nil
       #   None().presence || "fallback" # => "fallback"
+      #
+      # @example the Rails spelling of unwrap_or(nil), and no nudge with it
+      #   nudges = StringIO.new
+      #   original = $stderr
+      #   begin
+      #     $stderr = nudges
+      #     captured = Some("").presence
+      #     None().presence
+      #   ensure
+      #     $stderr = original
+      #   end
+      #   captured # => ""
+      #   nudges.string # => ""
       def presence
-        presence_nudge('presence', 'unwrap_or(nil)')
         return nil if none?
 
         value
@@ -312,6 +420,30 @@ module Errgonomic
         [value]
       end
 
+      # Yields the inner value once for a Some and not at all for a None, so
+      # an Option reads as the zero-or-one collection it is, and answers an
+      # Enumerator without a block. Option does not include Enumerable: its
+      # own filter and first answer Options, where Enumerable's answer plain
+      # values, and one name cannot mean both.
+      #
+      # @example
+      #   seen = []
+      #   Some(1).each { |x| seen << x } # => Some(1)
+      #   seen # => [1]
+      #   None().each { |x| seen << x } # => None()
+      #   seen # => [1]
+      #   Some(1).each.to_a # => [1]
+      #   None().each.to_a # => []
+      #   Some(2).each.map { |x| x * 3 } # => [6]
+      #   Some(1).each.size # => 1
+      #   None().each.size # => 0
+      def each(&block)
+        return to_enum(:each) { some? ? 1 : 0 } unless block
+
+        block.call(value) if some?
+        self
+      end
+
       # returns the inner value if present, else raises an error
       # @example
       #   Some(1).unwrap! # => 1
@@ -322,21 +454,28 @@ module Errgonomic
         value
       end
 
-      # returns the inner value if pressent, else raises an error with the given
-      # message
+      # Returns the inner value of a Some, else raises with the given message.
+      # A block is called only on the None branch, so a message that
+      # interpolates costs nothing on the path that succeeds.
+      #
       # @example
       #   Some(1).expect!("msg") # => 1
       #   None().expect!("here's why this failed") # => raise Errgonomic::ExpectError, "here's why this failed"
-      def expect!(msg)
-        raise Errgonomic::ExpectError, msg if none?
+      #   Some(1).expect! { "built only where it is raised" } # => 1
+      #   None().expect! { "no tier for #{7}" } # => raise Errgonomic::ExpectError, "no tier for 7"
+      def expect!(msg = nil, &block)
+        raise Errgonomic::ExpectError, block ? block.call : msg if none?
 
         value
       end
 
-      # returns the inner value if present, else returns the default value
+      # returns the inner value if present, else returns the default value.
+      # This is the spelling `opt || default` cannot give you: an Option is
+      # truthy, so `||` never reaches the fallback.
       # @example
       #   Some(1).unwrap_or(2) # => 1
       #   None().unwrap_or(2) # => 2
+      #   None() || 2 # => None()
       def unwrap_or(default)
         return default if none?
 
@@ -372,46 +511,49 @@ module Errgonomic
       end
 
       # Maps the Option to another Option by applying a function to the
-      # contained value (if Some) or returns None. Raises a pedantic exception
-      # if the return value of the block is not an Option.
+      # contained value (if Some) or returns None. Whatever the block returns
+      # is wrapped, as in Rust: a block that returns an Option gives
+      # Some(Some(x)). and_then is the spelling for a block that returns an
+      # Option.
       #
       # @example
       #   Some(1).map { |x| x + 1 } # => Some(2)
       #   None().map { |x| x + 1 } # => None()
+      #   Some(1).map { |x| Some(x + 1) } # => Some(Some(2))
+      #   Some(1).and_then { |x| Some(x + 1) } # => Some(2)
       def map(&block)
         return self if none?
 
         Some(block.call(value))
       end
 
-      # Returns the provided default (if none), or applies a function to the
-      # contained value (if some). If you want lazy evaluation for the provided
-      # value, use +map_or_else+.
+      # Returns the provided default (if none), or the block applied to the
+      # contained value (if some). Both come back bare, as Rust's map_or
+      # gives: this is the exit from the Option, where map stays inside it.
+      # Use +map_or_else+ when the default is expensive to build.
       #
       # @example
-      #   None().map_or(1) { 100 } # => Some(1)
-      #   Some(1).map_or(100) { |x| x + 1 } # => Some(2)
-      #   Some("foo").map_or(0) { |str| str.length } # => Some(3)
+      #   None().map_or(1) { 100 } # => 1
+      #   Some(1).map_or(100) { |x| x + 1 } # => 2
+      #   Some("foo").map_or(0) { |str| str.length } # => 3
+      #   Some(2).map_or(0) { |x| x * 2 } # => 4
       def map_or(default, &block)
-        return Some(default) if none?
+        return default if none?
 
-        Some(block.call(value))
+        block.call(value)
       end
 
       # Computes a default from the given Proc if None, or applies the block to
-      # the contained value (if Some).
+      # the contained value (if Some). Both come back bare, as map_or's do.
       #
       # @example
-      #   None().map_or_else(-> { :foo }) { :bar } # => Some(:foo)
-      #   Some("str").map_or_else(-> { 100 }) { |str| str.length } # => Some(3)
-      #   None().map_or_else( -> { nil }) { |str| str.length } # => None()
+      #   None().map_or_else(-> { :foo }) { :bar } # => :foo
+      #   Some("str").map_or_else(-> { 100 }) { |str| str.length } # => 3
+      #   None().map_or_else(-> { nil }) { |str| str.length } # => nil
       def map_or_else(proc, &block)
-        if none?
-          val = proc.call
-          return val ? Some(val) : None()
-        end
+        return proc.call if none?
 
-        Some(block.call(value))
+        block.call(value)
       end
 
       # convert the option into a result where Some is Ok and None is Err
@@ -536,13 +678,18 @@ module Errgonomic
         Some(other)
       end
 
-      # Refuse to serialize an unwrapped Option as a String. Options must be
-      # correctly handled to access their inner value.
+      # Render as inspect does. Rust gives Option a Debug and no Display, so
+      # refusing was faithful, but a to_s that raises replaces the real
+      # exception while a rescue builds its log line, and the rendered form
+      # says plainly that a wrapper arrived where a value was meant.
       #
       # @example
-      #   None().to_s # => raise Errgonomic::SerializeError, "cannot serialize an unwrapped Option"
+      #   Some(1).to_s # => "Some(1)"
+      #   Some("x").to_s # => "Some(\"x\")"
+      #   None().to_s # => "None"
+      #   "value: #{Some(1)}" # => "value: Some(1)"
       def to_s
-        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
+        inspect
       end
 
       # Refuse to serialize an unwrapped Option as JSON. Not only should we
@@ -551,9 +698,14 @@ module Errgonomic
       # Object#to_json implementations.
       #
       # @example
-      #   None().to_json # => raise Errgonomic::SerializeError, "cannot serialize an unwrapped Option"
+      #   None().to_json # => raise Errgonomic::SerializeError, 'cannot serialize an unwrapped None'
+      #   begin
+      #     Some('a' * 100).to_json
+      #   rescue Errgonomic::SerializeError => e
+      #     e.message.end_with?('...')
+      #   end # => true
       def to_json(*_args)
-        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
+        raise Errgonomic::SerializeError, serialize_refusal
       end
 
       # ActiveSupport's Hash#as_json and Array#as_json recurse through their
@@ -562,7 +714,7 @@ module Errgonomic
       # variables. Refuse there too, and the guard holds wherever an Option
       # travels.
       def as_json(*_args)
-        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
+        raise Errgonomic::SerializeError, serialize_refusal
       end
 
       # pp uses its own object dump unless told otherwise; keep it consistent
@@ -621,21 +773,48 @@ module Errgonomic
 
       private
 
+      # Name the value the caller failed to handle, bounded: an inspect of a
+      # record or a long payload would bury the message carrying it.
+      def serialize_refusal
+        rendered = inspect
+        rendered = "#{rendered[0, 57]}..." if rendered.length > 60
+        "cannot serialize an unwrapped #{rendered}"
+      end
+
       def presence_nudge(from, to)
+        return unless NUDGED.add?(from)
+
         warn "Errgonomic: `#{from}` on an Option is soft-deprecated; prefer `#{to}`."
       end
 
+      def strict_equality!(other, operator)
+        return unless Errgonomic.strict_equality?
+        return if other.is_a?(Errgonomic::Option::Any)
+
+        raise Errgonomic::TypeMismatchError,
+              "#{self.class} #{operator} #{other.class}, which strict equality refuses.\n" \
+              "#{strict_equality_remedy(other)}"
+      end
+
+      def strict_equality_remedy(other)
+        case other
+        when Errgonomic::Result::Any
+          'An Option and a Result are different containers, and neither is the other. ' \
+            'Unwrap the one you meant (opt.unwrap_or(nil) == res.unwrap_or(nil)).'
+        when nil
+          'Absence here is the discriminant: ask none?, or nil? under the Rails integration.'
+        else
+          "Compare Options (opt == Some(#{other.inspect})), test the inner value " \
+            "(opt.some_and? { |v| v == #{other.inspect} }), or unwrap_or a fallback first."
+        end
+      end
+
       def raise_blank_side_teaching(name)
         raise Errgonomic::UnwrappedAccessError.new(<<~MSG, name)
           `#{name}` is not supported on an Option, whose blankness is its discriminant.
           Test it with none?, or supply a fallback with unwrap_or / unwrap_or_else.
         MSG
       end
-
-      public
-
-      # Rust's mutating combinators (insert, get_or_insert, take, replace)
-      # are deliberately omitted: an Option here is a value, not a slot.
     end
 
     # Represent a value

data/lib/errgonomic/rails/active_record_delegate_optional.rb

@@ -4,10 +4,81 @@ module Errgonomic
   module Rails
     # Adds a `delegate_optional` class method in the spirit of Rails'
     # `delegate`, returning an Option instead of nil or NoMethodError when
-    # the delegation target is absent.
+    # the delegation target is absent. The generated reader forwards with
+    # `...` from inside a block, which Ruby 3.4, the version CI runs, accepts.
     module ActiveRecordDelegateOptional
       extend ActiveSupport::Concern
 
+      # What a declaration that cannot mean what it says is told, where it is
+      # written. A writer is refused rather than delegated: an assignment
+      # through an absent target has nowhere to put the value, and dropping it
+      # silently is the failure an Option exists to prevent.
+      NO_TARGET = "Delegation needs a target. Supply a keyword argument 'to' " \
+                  '(e.g. delegate_optional :hello, to: :greeter).'
+      NO_WRITERS = 'delegate_optional does not delegate a writer; an absent target would drop the value assigned'
+      NO_NAME_TO_PREFIX = "prefix: true takes the target's own name, and a module target has none; name the prefix"
+      NO_METHOD_TO_PREFIX = 'Can only automatically set the delegation prefix when delegating to a method.'
+      ALWAYS_NONE = 'delegate_optional reads an absent target as None; allow_nil: false asks for something else'
+      private_constant :NO_TARGET, :NO_WRITERS, :NO_NAME_TO_PREFIX, :NO_METHOD_TO_PREFIX, :ALWAYS_NONE
+
+      # YARD does not see through a concern's class_methods block, so the
+      # method it documents is declared rather than read.
+      #
+      # @!method delegate_optional(*methods, to: nil, prefix: nil, private: nil, allow_nil: nil)
+      #   @!scope class
+      #   Delegates to an optional target, answering an Option: None where the target is absent.
+      #   @example prefix forms name the reader, as they do for Rails' delegate
+      #     article = Article.create!(title: 'Omelas', writer: Writer.create!(name: 'Ursula', bio: 'writes'))
+      #     article.writer_name # => Some('Ursula')
+      #     article.author_name # => Some('Ursula')
+      #     article.bio # => Some('writes')
+      #   @example a delegated call forwards what it was handed
+      #     article = Article.create!(title: 'Omelas', writer: Writer.create!(name: 'Ursula'))
+      #     article.writer_greeting('Hello') # => Some('Hello, Ursula.')
+      #     article.writer_greeting('Hi', punctuation: '!') # => Some('Hi, Ursula!')
+      #     article.writer_styled_name(&:upcase) # => Some('URSULA')
+      #   @example a target named for a Ruby keyword is reached through self
+      #     Article.create!(title: 'Omelas').table_name # => Some('articles')
+      #   @example the target is lifted, and an Option it hands back is not nested
+      #     draft = Draft.create!(title: 'Omelas', writer_id: Writer.create!(name: 'Ursula').id)
+      #     draft.writer_name # => Some('Ursula')
+      #     draft.byline_name # => Some('Ursula')
+      #     Draft.create!(title: 'Untitled').writer_name # => None()
+      #     Article.create!(title: 'Untitled').writer_name # => None()
+      #   @example a delegated reader points at the model that declared it
+      #     Article.instance_method(:writer_name).source_location.first.end_with?('doctest_helper.rb') # => true
+      #   @example an absent target is a value here, so allow_nil: true says nothing new
+      #     Reprint.create!(title: 'Untitled').writer_name # => None()
+      #     Reprint.create!(title: 'Untitled').respond_to?(:bio) # => false
+      #     begin
+      #       Class.new(Reprint) { delegate_optional :name, to: :writer, allow_nil: false }
+      #     rescue ArgumentError => e
+      #       e.message
+      #     end # => 'delegate_optional reads an absent target as None; allow_nil: false asks for something else'
+      #   @example a delegation needs a target
+      #     begin
+      #       Class.new(Reprint) { delegate_optional :name }
+      #     rescue ArgumentError => e
+      #       e.message
+      #     end.start_with?("Delegation needs a target. Supply a keyword argument 'to'") # => true
+      #   @example a writer is not delegated
+      #     begin
+      #       Class.new(Reprint) { delegate_optional :name=, to: :writer }
+      #     rescue ArgumentError => e
+      #       e.message
+      #     end # => 'delegate_optional does not delegate a writer; an absent target would drop the value assigned'
+      #   @example a module target has no name to prefix with
+      #     begin
+      #       Class.new(Reprint) { delegate_optional :name, to: Errgonomic, prefix: true }
+      #     rescue ArgumentError => e
+      #       e.message
+      #     end # => "prefix: true takes the target's own name, and a module target has none; name the prefix"
+      #   @example an automatic prefix needs a target it can name a method after
+      #     begin
+      #       Class.new(Article) { delegate_optional :name, to: :@writer, prefix: true }
+      #     rescue ArgumentError => e
+      #       e.message
+      #     end # => 'Can only automatically set the delegation prefix when delegating to a method.'
       class_methods do
         # Names attributes that ActiveRecordOptional must leave alone. It has to
         # be callable before the include, which is what starts the wrapping for
@@ -25,19 +96,108 @@ module Errgonomic
             superclass.respond_to?(:errgonomic_optional_exceptions) ? superclass.errgonomic_optional_exceptions.dup : []
         end
 
-        def delegate_optional(*methods, to: nil, prefix: nil, private: nil)
-          return if to.nil?
+        # How a None reaches a payload. :null writes it as null, which is
+        # what Rails does with nil and what serde does with None unless a
+        # field asks otherwise, so it is the default and needs no
+        # declaration. :omit leaves the key out instead. only: and except:
+        # scope the mode to named readers, and a reader outside the scope
+        # keeps the default. Configuration reads as well above the include
+        # as below it, so it lives here rather than in the concern.
+        def errgonomic_serialize_none(mode, only: nil, except: nil)
+          complaint = errgonomic_serialize_none_complaint(mode, only, except)
+          raise ::ArgumentError, "errgonomic_serialize_none #{complaint}" if complaint
+
+          @errgonomic_serialize_none = {
+            mode: mode,
+            only: only && Array(only).map(&:to_s),
+            except: except && Array(except).map(&:to_s)
+          }
+        end
+
+        # The nearest declaration is the whole story for a class: it replaces
+        # whatever it inherits rather than layering onto it, so a scoped one
+        # leaves every reader it does not name at the default.
+        def errgonomic_serialize_none_declaration
+          return @errgonomic_serialize_none if defined?(@errgonomic_serialize_none)
+          return nil unless superclass.respond_to?(:errgonomic_serialize_none_declaration)
+
+          superclass.errgonomic_serialize_none_declaration
+        end
+
+        # A declaration that cannot change what a payload looks like is a
+        # mistake rather than a no-op, so say what to write instead. :null is
+        # already what every unnamed reader gets, so scoping it names one set
+        # of readers for the default and leaves the rest at the default too.
+        def errgonomic_serialize_none_complaint(mode, only, except)
+          return "takes :null or :omit, not #{mode.inspect}" unless %i[null omit].include?(mode)
+          return 'takes only: or except:, not both; name the readers on one of them' if only && except
+          return unless mode == :null && (only || except)
+
+          ':null is the default for every reader and takes no only: or except:; ' \
+            'declare :omit on the readers to leave out'
+        end
+
+        def delegate_optional(*methods, to: nil, prefix: nil, private: nil, allow_nil: nil)
+          declared_at = caller_locations(1, 1).first
+          complaint = delegate_optional_complaint(methods, to, prefix, allow_nil)
+          raise ::ArgumentError, complaint if complaint
 
+          receiver = delegate_optional_receiver(to)
           methods.each do |method_name|
-            prefixed_method_name = prefix == true ? "#{to}_#{method_name}" : method_name
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def #{prefixed_method_name}
-                #{to}.map { |obj| obj.send(:#{method_name}) }
-              end
-            RUBY
-            send(:private, prefixed_method_name) if private
+            reader = "#{delegate_optional_prefix(to, prefix)}#{method_name}"
+            define_optional_delegation(receiver, method_name, reader, declared_at)
+            private(reader) if private
           end
         end
+
+        # Both ends lift exactly one layer, so a record, a nil and an Option
+        # all delegate, and an Option the call returns is not wrapped twice.
+        # The call is written out rather than sent, so the target's method is
+        # reached on the same terms a caller would reach it on, and the reader
+        # takes the declaration's file and line so a backtrace names the model.
+        def define_optional_delegation(receiver, method_name, reader, declared_at)
+          class_eval <<-RUBY, declared_at.path, declared_at.lineno # rubocop:disable Style/EvalWithLocation
+            def #{reader}(...)
+              #{receiver}.to_option.and_then { |target| target.#{method_name}(...).to_option }
+            end
+          RUBY
+        end
+
+        # A target named for a Ruby keyword reads as the keyword in the body
+        # it is written into, so it needs an explicit receiver. Rails answers
+        # the same question for delegate, and answers it for the same names.
+        def delegate_optional_receiver(to)
+          return to.to_s unless ::ActiveSupport::Delegation::RESERVED_METHOD_NAMES.include?(to.to_s)
+
+          "self.#{to}"
+        end
+
+        # true asks for the target's own name; any other prefix is the name.
+        def delegate_optional_prefix(to, prefix)
+          return '' unless prefix
+
+          "#{prefix == true ? to : prefix}_"
+        end
+
+        # A mistake is worth more where the declaration is written than as a
+        # method nothing can call. allow_nil: true is what a delegation does
+        # here anyway, so a swap from delegate carries; its opposite does not.
+        def delegate_optional_complaint(methods, to, prefix, allow_nil)
+          return NO_TARGET if to.nil?
+          return NO_WRITERS if methods.any? { |method_name| /\A\w+=\z/.match?(method_name.to_s) }
+          return ALWAYS_NONE if allow_nil == false
+
+          delegate_optional_prefix_complaint(to, prefix)
+        end
+
+        # An automatic prefix is the target's own name, so the target needs
+        # one, and one that can start a method name.
+        def delegate_optional_prefix_complaint(to, prefix)
+          return unless prefix == true
+          return NO_NAME_TO_PREFIX if to.is_a?(::Module)
+
+          NO_METHOD_TO_PREFIX if /^[^a-z_]/.match?(to.to_s)
+        end
       end
     end
   end