errgonomic 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 124c029eafbcbb48377836a8facaaea281559a922924d544bd7ce3a6b47d0ad8
-  data.tar.gz: '089786b6eb3ce3be3068803da318543f50dd33878d2b453d22e68296888d7a85'
+  metadata.gz: 94eb90cd1a2a6e07d42a5bc9318fc34cea84cff058c6d78299c2aa1673279b3e
+  data.tar.gz: c8516b096821a7a1902805687a51b7f07f1443adeccf50f3b85659006f431b61
 SHA512:
-  metadata.gz: b7d3e991e2d9981f08fc6ea8437f2052b1ae6ba08e20831867c48f6cdc37cb8907697f33a7fee3c4ab3cb91bf6e8768c1a551a7892e0070172b49d6220deeed1
-  data.tar.gz: e0c8fb408cdae888b7475c15a91ca597f4f57463997101cabbca8fe91318f912b3fa490689ef4caa05858d68ad3e0477a45ad723142f38941e5d7ba12ee54cfb
+  metadata.gz: 4a3803504c4789e6bf2df90f28348e90f72089121e2a2b06f2ba8ec28db7082286447ff07ca6c2c23cd5a41e38d86e31b454237ae3d2299ed4d1f97d0b57518a
+  data.tar.gz: c868b2d29da869091801aac2b5295b5a69a67ac405a9a14d38e62021048ff5133dfd288d61caadbfb783f512da3cd409fda19453c55a13610a8525af6a2b46fb

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [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.

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.
 

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/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/version.rb

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

metadata

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