errgonomic 0.10.1 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 543390fc5f85546ffde4785cfc41951400800094506078271cfe32535e9d784a
-  data.tar.gz: 8d5cdf061dbf7026eaab5ba8cab628368c600943699dbad04235c9d1d9bd3f5a
+  metadata.gz: 124c029eafbcbb48377836a8facaaea281559a922924d544bd7ce3a6b47d0ad8
+  data.tar.gz: '089786b6eb3ce3be3068803da318543f50dd33878d2b453d22e68296888d7a85'
 SHA512:
-  metadata.gz: ad7cbe42d7f1d65549323c026a3f4486d4e64a9b5274023fc3eebb0a576ceb09c030151d176512220e13ef8d6e1bc3c2bff78162783ecb286bbb6805ac16c8c9
-  data.tar.gz: 4588909f84b800a1c497882d030fd88f23606146fe64b7ae02ecc8b7f4406ba2c5dd749d0c709c7004717de80a9a69e73d6247b2ce11013446fa25db66271c3d
+  metadata.gz: b7d3e991e2d9981f08fc6ea8437f2052b1ae6ba08e20831867c48f6cdc37cb8907697f33a7fee3c4ab3cb91bf6e8768c1a551a7892e0070172b49d6220deeed1
+  data.tar.gz: e0c8fb408cdae888b7475c15a91ca597f4f57463997101cabbca8fe91318f912b3fa490689ef4caa05858d68ad3e0477a45ad723142f38941e5d7ba12ee54cfb

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [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

@@ -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/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/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.10.2'
 end

metadata

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