errgonomic 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 543390fc5f85546ffde4785cfc41951400800094506078271cfe32535e9d784a
-  data.tar.gz: 8d5cdf061dbf7026eaab5ba8cab628368c600943699dbad04235c9d1d9bd3f5a
+  metadata.gz: 94eb90cd1a2a6e07d42a5bc9318fc34cea84cff058c6d78299c2aa1673279b3e
+  data.tar.gz: c8516b096821a7a1902805687a51b7f07f1443adeccf50f3b85659006f431b61
 SHA512:
-  metadata.gz: ad7cbe42d7f1d65549323c026a3f4486d4e64a9b5274023fc3eebb0a576ceb09c030151d176512220e13ef8d6e1bc3c2bff78162783ecb286bbb6805ac16c8c9
-  data.tar.gz: 4588909f84b800a1c497882d030fd88f23606146fe64b7ae02ecc8b7f4406ba2c5dd749d0c709c7004717de80a9a69e73d6247b2ce11013446fa25db66271c3d
+  metadata.gz: 4a3803504c4789e6bf2df90f28348e90f72089121e2a2b06f2ba8ec28db7082286447ff07ca6c2c23cd5a41e38d86e31b454237ae3d2299ed4d1f97d0b57518a
+  data.tar.gz: c868b2d29da869091801aac2b5295b5a69a67ac405a9a14d38e62021048ff5133dfd288d61caadbfb783f512da3cd409fda19453c55a13610a8525af6a2b46fb

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-16
+
+This release makes a converted model's query methods and a delegated predicate answer the verdict a boolean caller asked for, rather than something an `if` reads as true.
+
+### Upgrading from 0.10.2
+
+An application that prepended its own `query_attribute` unwrap to work around a wrapped column's `attr?` answering true for `false`, `0` or `""` can delete it: the concern does it now, and a prepended copy is redundant rather than harmful. A `delegate_optional` whose method name ends in `?` returns `true` or `false` where it returned an Option, so `some?`, `unwrap_or` and the other combinators on that result are a `NoMethodError`. Read the boolean instead. The one loss is a `?` method that answers a value by design, which now answers `true`: declare it without the `?`, or write `some_and?` by hand. The seam to watch is `Object#to_option`, which lifts whatever it is handed, so `record.delegated?.to_option` is `Some(false)` for an absent target where it was `None`.
+
+### Changes
+
+- [Bug fix] A converted model's `query_attribute`, its private `attribute?` alias and the `attr?` methods Rails generates from them answer what the unconverted model answers for a wrapped column, so `note.pinned?` is `false` for an explicit `false` and `note.rank?` is `false` for a `0`. The concern overrides `query_attribute` to unwrap the reader's Option before handing the value to Rails' own cast. Previously the cast saw a `Some`, missed its `true` and `false, nil` arms and fell through to `!blank?`, where `Option#blank?` is `none?`, so every present value answered true ([#88](https://github.com/omc/errgonomic/issues/88))
+- [Behavior change] `delegate_optional` with a method name ending in `?` answers `true` or `false` through `some_and?`, reading an absent target as `false`, where it answered `Some(true)`, `Some(false)` and `None` before. A `?` name asks for a verdict and no Option can serve as one, because every Option is truthy: `Some(false)` and `None` both took the true branch of an `if`, which is the silent wrong branch that `delegate ..., allow_nil: true` does not have. Every other name is lifted into an Option as before, and there is no opt-out keyword ([#89](https://github.com/omc/errgonomic/issues/89))
+
+## [0.10.2] - 2026-09-10
+
+This release makes every `Err` carry an error and removes `Option#ok`, the one method that built an `Err` without one.
+
+### Upgrading from 0.10.1
+
+Replace `Err()` with `Err(reason)`, and a pattern `in Err()` with `in Err` or `in Err(_)`: `Err()` and `Errgonomic::Result::Err.new` with no argument raise `ArgumentError`, and `in Err()` no longer matches any `Err`. Replace `opt.ok` with `opt.ok_or(reason)`; `ok` on an Option now raises `Errgonomic::UnwrappedAccessError`, which names `ok_or` and `ok_or_else`.
+
+### Changes
+
+- [Behavior change] `Err()` and `Errgonomic::Result::Err.new` with no argument raise `ArgumentError`. A value-less `Err` held an internal placeholder, `Errgonomic::Result::Err::Arbitrary`, which `unwrap_err!` handed back to the caller, a gem-internal value leaking into application data. The placeholder is deleted along with the special case that made `Err().deconstruct` answer `[]`, so `Err(e).deconstruct` is always `[e]`, `in Err(e)` and `in Err(_)` match every `Err`, and `in Err()` matches none. `Err(nil)` is unchanged: it carries `nil`
+- `Option#ok` is removed. `None().ok` was the only method that returned a value-less `Err`, and Rust has no `Option::ok`; `ok_or` and `ok_or_else` make the caller name the error
+- [Docs] The README's Known limitations section names a converted model's `belongs_to ..., optional: true, touch: true`, which raises `Errgonomic::UnwrappedAccessError` on a save or a destroy with the association absent because a `None` does not delegate `persisted?`, and gives `errgonomic_optional_except` as the way around it. The limitation predates 0.10.2
+
 ## [0.10.1] - 2026-09-10
 
 This release makes cross-type equality raise unconditionally and removes the switch that used to turn it on.

data/README.md

@@ -403,7 +403,7 @@ The declaration reads as well above the include as below it, as `errgonomic_opti
 
 `Model.errgonomic_optionals` reports which readers a model wrapped, including nullable foreign-key columns, so `book.author_id` is `Some(1)` alongside `book.author`. That is how to check that a conversion did what it meant to. A subclass reports what it inherited alongside anything it wrapped itself, so the report names every wrapped reader the class responds to; `Model.errgonomic_optional_names` is the set that class wrapped on its own.
 
-`delegate_optional` is Rails' `delegate` with `allow_nil`, where the absent case is a `None` rather than a `nil`: `delegate_optional :name, to: :author` gives `book.name # => Some('Cixin Liu')`, and `None()` where there is no author. The prefix forms are Rails': `prefix: true` names the reader after the target (`author_name`), and `prefix: :writer` names it `writer_name`. `private: true` works as it does there. The reader forwards whatever it was called with, arguments and block alike. `allow_nil: true` is accepted and says nothing new, so a `delegate` declaration swaps over unchanged unless it delegates a writer. `delegate_optional :name=, to: :author` raises instead: an assignment through an absent target has nowhere to put the value, and dropping it silently is what the type is there to prevent. `allow_nil: false` asks for a reader that raises on absence, which this does not have, so it raises `ArgumentError` where it is written, as a declaration with no `to:` does.
+`delegate_optional` is Rails' `delegate` with `allow_nil`, where the absent case is a `None` rather than a `nil`: `delegate_optional :name, to: :author` gives `book.name # => Some('Cixin Liu')`, and `None()` where there is no author. The prefix forms are Rails': `prefix: true` names the reader after the target (`author_name`), and `prefix: :writer` names it `writer_name`. `private: true` works as it does there. The reader forwards whatever it was called with, arguments and block alike. `allow_nil: true` is accepted and says nothing new, so a `delegate` declaration swaps over unchanged unless it delegates a writer or a predicate. A name ending in `?` asks for a verdict, and no Option can serve as one, because every Option is truthy. So a predicate answers a bare `true` or `false` through `some_and?`: `delegate_optional :prolific?, to: :author` gives `book.prolific? # => false` for an unprolific author, and `false` again where there is no author, which branches an `if` the way Rails' `allow_nil: true` does. The one thing that costs is a `?` method that answers a value by design, which now answers `true`; declare it without the `?`, or write `some_and?` by hand. `delegate_optional :name=, to: :author` raises instead: an assignment through an absent target has nowhere to put the value, and dropping it silently is what the type is there to prevent. `allow_nil: false` asks for a reader that raises on absence, which this does not have, so it raises `ArgumentError` where it is written, as a declaration with no `to:` does.
 
 It is available on every model, converted or not, because it lifts both ends one layer. The target is lifted, so a plain record reads as `Some` and a `nil` as `None`. What the delegated call returns is lifted too, so a delegated reader that is itself an Option comes back as one Option rather than two.
 
@@ -423,6 +423,10 @@ This is the register of where the gem leaves the Rust idiom, and why. ActiveReco
 
 The set is closed. If a future integration appears to need a sixth compromise, that is a signal ActiveRecord is pushing back somewhere unmapped, and it warrants a design discussion rather than a quiet patch. `errgonomic_optional_except` and `errgonomic_serialize_none` are deliberately not on the list: they are configuration, an escape hatch that softens the all-or-nothing include for whatever conflict shows up next and a choice of how an absent value is written, rather than semantic exceptions.
 
+#### Known limitations
+
+A converted model with `belongs_to :writer, optional: true, touch: true` raises `Errgonomic::UnwrappedAccessError` (``undefined method `persisted?' for None``) when it saves or is destroyed with the association absent: on `create`, on any `update`, and on `destroy`. ActiveRecord's touch callback reads the association back through the public reader and asks `record && record.persisted?`, and a `None` is truthy and does not delegate `persisted?` the way a `Some` does. Leave the association unwrapped with `errgonomic_optional_except :writer`, which keeps `touch: true` working and hands back `nil` for an absent record.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. The repository is a self-contained Nix flake; with direnv, `direnv allow` puts the right toolchain on your path.

data/doctest_helper.rb

@@ -76,6 +76,10 @@ class Writer < ActiveRecord::Base
   def styled_name
     yield(name)
   end
+
+  def credited?
+    !bio.nil?
+  end
 end
 
 # A converted model reads its association as an Option.
@@ -86,6 +90,7 @@ class Article < ActiveRecord::Base
   delegate_optional :name, to: :writer, prefix: :author
   delegate_optional :bio, to: :writer
   delegate_optional :greeting, :styled_name, to: :writer, prefix: true
+  delegate_optional :credited?, to: :writer
   delegate_optional :table_name, to: :class
 end
 

data/lib/errgonomic/option.rb

@@ -626,21 +626,24 @@ module Errgonomic
         block.call(value)
       end
 
-      # convert the option into a result where Some is Ok and None is Err
-      # @example
-      #   None().ok # => Err()
-      #   Some(1).ok # => Ok(1)
-      def ok
-        return Errgonomic::Result::Ok.new(value) if some?
-
-        Errgonomic::Result::Err.new
-      end
-
       # Transforms the option into a result, mapping Some(v) to Ok(v) and None to Err(err)
       #
       # @example
       #   None().ok_or("wow") # => Err("wow")
       #   Some(1).ok_or("such err") # => Ok(1)
+      #
+      # @example there is no bare ok: an Err always names its error
+      #   begin
+      #     None().ok
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   begin
+      #     Some(1).ok
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   Some(1).respond_to?(:ok) # => false
       def ok_or(err)
         return Errgonomic::Result::Ok.new(value) if some?
 

data/lib/errgonomic/rails/active_record_delegate_optional.rb

@@ -27,6 +27,11 @@ module Errgonomic
       # @!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.
+      #   A name ending in `?` is the exception: it answers a bare boolean, false for an absent target.
+      #   @example a predicate answers a verdict rather than an Option, since every Option is truthy
+      #     Article.create!(title: 'Omelas', writer: Writer.create!(name: 'Ursula', bio: 'writes')).credited? # => true
+      #     Article.create!(title: 'Omelas', writer: Writer.create!(name: 'Ursula')).credited? # => false
+      #     Article.create!(title: 'Untitled').credited? # => false
       #   @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')
@@ -158,11 +163,25 @@ module Errgonomic
         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 }
+              #{delegation_body(receiver, method_name)}
             end
           RUBY
         end
 
+        # A ? name asks for a verdict, and an Option is not usable as one:
+        # every Option is truthy, so Some(false) and None both take the true
+        # branch. A predicate therefore answers a bare boolean, reading an
+        # absent target as false, which branches the way nil does.
+        def delegation_body(receiver, method_name)
+          return "#{receiver}.to_option.some_and? { |target| target.#{method_name}(...) }" if predicate?(method_name)
+
+          "#{receiver}.to_option.and_then { |target| target.#{method_name}(...).to_option }"
+        end
+
+        def predicate?(method_name)
+          method_name.to_s.end_with?('?')
+        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.

data/lib/errgonomic/rails/active_record_optional.rb

@@ -38,10 +38,12 @@ module Errgonomic
     #    Validation unwraps at read_attribute_for_validation, the seam every
     #    EachValidator fetches an attribute through; serialization at
     #    read_attribute_for_serialization, the seam every attribute in a
-    #    payload is fetched through; and a form helper at ActionView's tag
-    #    value, the seam every field reads its record through. So a standard
-    #    validator weighs the value, a payload carries it and a form renders
-    #    it, rather than the wrapper. A singular association with nested
+    #    payload is fetched through; a form helper at ActionView's tag
+    #    value, the seam every field reads its record through; and a query
+    #    method at query_attribute, the seam every generated attr? is cast
+    #    through. So a standard validator weighs the value, a payload carries
+    #    it, a form renders it and a query method answers for it, rather than
+    #    for the wrapper. A singular association with nested
     #    attributes goes further and keeps its plain reader: nested attributes
     #    are assigned through the reader, and ActiveRecord asks whatever it
     #    finds there whether it is a new record. So does a reader a framework
@@ -115,6 +117,29 @@ module Errgonomic
         errgonomic_omit_absent_keys(hash)
       end
 
+      # A query method reads the record through the public reader and matches
+      # what it finds against true, then false and nil, before falling through
+      # to blankness. An Option is none of those, and its blankness is its
+      # discriminant rather than its value, so an explicit false and a stored
+      # zero would answer true. Unwrapping the read is what keeps the answer
+      # the one an unconverted model gives.
+      #
+      # @example
+      #   Note.new(pinned: false).pinned? # => false
+      #   Note.new(rank: 0).rank? # => false
+      #   Note.new(title: '').title? # => false
+      #   Note.new(pinned: true).pinned? # => true
+      #   Note.new(rank: 3).rank? # => true
+      def query_attribute(attr_name)
+        query_cast_attribute(attr_name, Errgonomic::Rails.unwrap_option(public_send(attr_name)))
+      end
+
+      # Rails copies query_attribute into attribute? at the alias, and the
+      # attr? methods it generates call that copy, so an override of the one
+      # never reaches them.
+      alias attribute? query_attribute
+      private :attribute?
+
       # YARD does not see through a concern's class_methods block, so the
       # method it documents is declared rather than read.
       #

data/lib/errgonomic/result.rb

@@ -5,8 +5,8 @@ require_relative 'variant_name'
 module Errgonomic
   module Result
     # The base class for Result's Ok and Err class variants. We implement as
-    # much logic as possible here, and let Ok and Err handle their
-    # initialization and self identification.
+    # much logic as possible here, including construction, and let Ok and
+    # Err handle only their self identification.
     class Any
       include Comparable
 
@@ -27,7 +27,7 @@ module Errgonomic
       #   end # => Errgonomic::UnwrappedAccessError
       #   Ok(1).respond_to?(:value) # => false
       #   Ok(1).frozen? # => true
-      #   Err().frozen? # => true
+      #   Err(:x).frozen? # => true
       def initialize(value)
         @value = value
         freeze
@@ -124,7 +124,7 @@ module Errgonomic
       #   Ok(1) == 1 # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Ok == Integer, which strict equality refuses.\nCompare Results (res == Ok(1)), test the inner value (res.ok_and? { |v| v == 1 }), or unwrap_or a fallback first."
       #   Ok(1) != 1 # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Ok != Integer, which strict equality refuses.\nCompare Results (res == Ok(1)), test the inner value (res.ok_and? { |v| v == 1 }), or unwrap_or a fallback first."
       #   Ok(1) === 1 # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Ok === Integer, which strict equality refuses.\nCompare Results (res == Ok(1)), test the inner value (res.ok_and? { |v| v == 1 }), or unwrap_or a fallback first."
-      #   Err() == nil # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Err == NilClass, which strict equality refuses.\nCompare Results (res == Ok(nil)), test the inner value (res.ok_and? { |v| v == nil }), or unwrap_or a fallback first."
+      #   Err(:x) == nil # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Err == NilClass, which strict equality refuses.\nCompare Results (res == Ok(nil)), test the inner value (res.ok_and? { |v| v == nil }), or unwrap_or a fallback first."
       #   Ok(1) === Ok(1) # => true
       #   begin
       #     [Ok(1)].include?(1)
@@ -132,7 +132,7 @@ module Errgonomic
       #     e.class
       #   end # => Errgonomic::TypeMismatchError
       #   { Ok(1) => :v }[1] # => nil
-      #   nil == Err() # => false
+      #   nil == Err(:x) # => false
       #
       # @example an Option is another container, not another Result
       #   Ok(1) == Some(1) # => raise Errgonomic::TypeMismatchError, "Errgonomic::Result::Ok == Errgonomic::Option::Some, which strict equality refuses.\nA Result and an Option are different containers, and neither is the other.\nUnwrap the one you meant (res.unwrap_or(nil) == opt.unwrap_or(nil))."
@@ -468,35 +468,37 @@ module Errgonomic
       end
 
       # The Rust shape: each variant deconstructs to its one payload, so
-      # `in Ok(v)` binds the value and `in Err(e)` binds the error. A
-      # value-less Err deconstructs to nothing: the sentinel behind it is
-      # internal and must never bind to a pattern variable.
+      # `in Ok(v)` binds the value and `in Err(e)` binds the error.
       #
       # @example
       #   Ok(1).deconstruct # => [1]
-      #   Err(:e).deconstruct # => [:e]
-      #   Err().deconstruct # => []
+      #   Err(:x).deconstruct # => [:x]
       #   Ok(1).respond_to?(:deconstruct_keys) # => false
       #
-      # @example a value-less Err matches `in Err` and `in Err()`, never `in Err(e)`
-      #   case Err()
-      #   in Err(e) then e
-      #   in Err then :no_value
-      #   end # => :no_value
-      #   case Err()
-      #   in Err() then :no_value
-      #   end # => :no_value
+      # @example every Err carries an error, so `in Err()` matches none of them
       #   case Err(:x)
+      #   in Err() then :empty
       #   in Err(e) then e
-      #   in Err then :no_value
       #   end # => :x
-      #   begin
-      #     case Err()
-      #     in Err(e) then e
-      #     end
-      #   rescue NoMatchingPatternError => e
-      #     e.class
-      #   end # => NoMatchingPatternError
+      #   case Err(:x)
+      #   in Err then :any_err
+      #   end # => :any_err
+      #   case Err(:x)
+      #   in Err(_) then :any_err
+      #   end # => :any_err
+      #
+      # @example an Err nested in an Ok matches through the Ok's payload
+      #   case Ok(Err(:boom))
+      #   in Ok(Err(e)) then e
+      #   end # => :boom
+      #   case Ok(Err(:boom))
+      #   in Ok(Err()) then :empty
+      #   in Ok(Err(_)) then :err_inside
+      #   end # => :err_inside
+      #   case Ok(Err(:boom))
+      #   in Ok(Ok(value)) then value
+      #   in Ok(Err) then :err_inside
+      #   end # => :err_inside
       #
       # @example a two-branch case/in with no else is exhaustive
       #   case Ok(1)
@@ -537,8 +539,6 @@ module Errgonomic
       #     "Measurement produced an exception -- #{e.class}: #{e}"
       #   end # => "Measurement produced an exception -- StandardError: nope"
       def deconstruct
-        return [] if value.equal?(Err::Arbitrary)
-
         [value]
       end
 
@@ -608,19 +608,23 @@ module Errgonomic
       end
     end
 
-    # The Err variant.
+    # The Err variant. It always carries an error, so unwrap_err! and a
+    # pattern variable bind what the caller put there.
+    #
+    # @example an Err without an error raises
+    #   Err(:e).unwrap_err! # => :e
+    #   Err() # => raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
+    #   Errgonomic::Result::Err.new # => raise ArgumentError, "wrong number of arguments (given 0, expected 1)"
+    #
+    # @example Err(nil) is an ordinary Err that holds nil
+    #   Err(nil).inspect # => "Err(nil)"
+    #   Err(nil).unwrap_err! # => nil
+    #   Err(nil).deconstruct # => [nil]
+    #   case Err(nil)
+    #   in Ok(value) then [:ok, value]
+    #   in Err(e) then [:err, e]
+    #   end # => [:err, nil]
     class Err < Any
-      class Arbitrary; end
-
-      # Err may be constructed without a value, if you want.
-      #
-      # @example
-      #   Err(:y).unwrap_err! # => :y
-      #   Err().unwrap_err! # => Arbitrary
-      def initialize(value = Arbitrary)
-        super(value)
-      end
-
       # Err is always err
       #
       # @example
@@ -637,15 +641,12 @@ module Errgonomic
         false
       end
 
-      # Render like Rust's Debug; a value-less Err renders bare.
+      # Render like Rust's Debug, delegating to the inner value's inspect.
       #
       # @example
       #   Err(:nope).inspect # => "Err(:nope)"
-      #   Err().inspect # => "Err()"
       #   Err(Some(1)).inspect # => "Err(Some(1))"
       def inspect
-        return 'Err()' if value.equal?(Arbitrary)
-
         "Err(#{value.inspect})"
       end
     end
@@ -687,7 +688,7 @@ def Ok(value)
 end
 
 # Global convenience method for constructing an Err result.
-def Err(value = Errgonomic::Result::Err::Arbitrary)
+def Err(value)
   Errgonomic::Result::Err.new(value)
 end
 

data/lib/errgonomic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Errgonomic
-  VERSION = '0.10.1'
+  VERSION = '0.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Nick Zadrozny