errgonomic 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b7d451a7e98b347baa9556bf72fd22d3825278bf03afddb9a4fdb0e7c325b03
-  data.tar.gz: b336d798fc24356fc0a340ac24d5c562d10d242d5507a71444daa881831ecb27
+  metadata.gz: c579e542517b446e381c09ef98e24237e8ba5c02ca19633d762195d9bcab6a1d
+  data.tar.gz: aa72fb5647fbd9f335bde9b0d10e6a07b68359a7581c4f9152fbf59958d54f43
 SHA512:
-  metadata.gz: 3967b76933831abb7750f253f345a8845c4bd00a172db427d99cd22c5fd3f41d9d18b36a7a44f4f915b04acca72009f52e4927ec8dfa60d98bea80eda82e1a2c
-  data.tar.gz: 2a7ef8d3aa5dbd1e9777e8a653a48c5d3eafbf1b8514e26a483e3056b5139dce643ace35542062512da59b2fa0c9d4b5ab915754e83e747196dabe65f6af91f8
+  metadata.gz: 6423f7d1dbf8a9b0d0ee116f72f7dcd427da888f2213c5ea55ebb13fa7abcec83c63d1897f253a6f644094dabf194c9711f99565bedca9444126951ae715c39e
+  data.tar.gz: 4d3329007ccb658b05cbb4103395133a2c355e4224f5b58850e3da399338ede381bcb0b4db3a2dcb08db54868405d8886e168b1e1b67435e484e9a94e2832f94

data/README.md

@@ -113,6 +113,8 @@ An unhandled Option refuses to leak into your output: `to_s` and `to_json` raise
 
 Presence follows the discriminant, as in Rust: `Some` is `present?` and `None` is `blank?`, regardless of the wrapped value. So `Some(false).present?` and `Some(nil).present?` are both `true`. If you care about the inner value's own presence, unwrap it first.
 
+The presence helpers are soft-deprecated on Options in favor of the combinators. The present side unwraps, where on any other object it returns the receiver — `Some(v).present_or_raise!(msg)`, `present_or(default)`, `present_or_else { }`, and `presence` all yield `v`, and `None` raises, substitutes, or answers `nil` — and each call prints a one-line stderr nudge naming the combinator to use instead (`expect!`, `unwrap_or`, `unwrap_or_else`, `unwrap_or(nil)`). The blank side (`blank_or*`) raises `UnwrappedAccessError` outright: an Option's blankness is its discriminant, so test it with `none?`.
+
 Equality is between Options only: `Some(5) == Some(5)`, but `Some(5) == 5` and `None() == nil` are `false`. That is quiet, never an error, matching how every Ruby object compares across types. Rust rejects `Some(5) == 5` at compile time; Ruby cannot, so guard the idiom in review and tests: compare against a wrapped value (`opt == Some(5)`) or test the inner value (`opt.some_and? { |v| v == 5 }`).
 
 ### Result
@@ -199,21 +201,31 @@ end
 
 When `Rails::Railtie` is defined, Errgonomic installs a Railtie with two opt-in integrations for ActiveRecord:
 
-- `include Errgonomic::Rails::ActiveRecordOptional` in a model makes its nullable attributes and `optional: true` associations return `Some(value)` or `None()` instead of a value-or-nil. This is all-or-nothing per model: every nullable column and optional association is wrapped, with no per-attribute opt-in.
+- `include Errgonomic::Rails::ActiveRecordOptional` in a model makes its nullable attributes and `optional: true` associations return `Some(value)` or `None()` instead of a value-or-nil. Every nullable column and optional association is wrapped, with no per-attribute opt-in. Two kinds of attribute stay unwrapped: those declared with `encrypts`, whose surrounding machinery reads the raw value, and those named by `errgonomic_optional_except`, which must appear before the include.
+
+```ruby
+class Credential < ApplicationRecord
+  errgonomic_optional_except :legacy_token
+  include Errgonomic::Rails::ActiveRecordOptional
+
+  encrypts :access_secret   # also left unwrapped, declared either side of the include
+end
+```
 - `delegate_optional :name, to: :association` (available on all models) delegates through an optional association, returning an Option instead of raising on nil.
 
 `Object#to_option` is also available in Rails to lift any value into an Option (`nil.to_option # => None()`).
 
 #### ActiveRecord compromises
 
-ActiveRecord assumes things about accessors that a strict Rust Option cannot satisfy, so the integration carries four deliberate compromises. Everywhere else, treat a departure from Rust's `Option` semantics as a bug; these four are intended:
+ActiveRecord assumes things about accessors that a strict Rust Option cannot satisfy, so the integration carries five deliberate compromises. Everywhere else, treat a departure from Rust's `Option` semantics as a bug; these five are intended:
 
 1. `None#nil?` answers `true`, so ActiveRecord internals and ordinary `.nil?` checks treat an absent value as absent. Equality does not follow suit: `None() == nil` is still `false`.
 2. `Some` delegates `persisted?`, `marked_for_destruction?`, and `touch_later` to its record, so a `Some` can stand in for its record during persistence.
-3. Quoting is patched so an `Option` passed into `where`/`quote` is unwrapped at the SQL boundary.
+3. Quoting and the predicate builder are patched so an `Option` passed into `where`/`quote` is unwrapped at the SQL boundary: `Some(v)` binds exactly as `v`, and `None()` as `nil`, so a hash condition asks for `IS NULL`. An array of Options unwraps too. An Option interpolated into raw SQL (`where("id = ?", opt)`) still raises, as it should.
 4. `SomeValidator` provides a presence-style validation for Option attributes.
+5. Attributes declared with `encrypts` are never wrapped: ActiveRecord Encryption's own machinery (a length validator it registers outside `Model.validators`) reads the raw value and cannot survive an Option.
 
-The set is closed. If a future integration appears to need a fifth compromise, that is a signal ActiveRecord is pushing back somewhere unmapped, and it warrants a design discussion rather than a quiet patch.
+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` is deliberately not on the list: it is configuration, an escape hatch that softens the all-or-nothing include for whatever conflict shows up next, rather than a semantic exception.
 
 ## Development
 

data/lib/errgonomic/option.rb

@@ -194,6 +194,114 @@ module Errgonomic
         none?
       end
 
+      # 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.
+
+      # Returns the inner value of a Some, and raises on a None. Presence
+      # follows the discriminant, so Some(nil) yields nil.
+      #
+      # @param message [String] The error message to raise on a None.
+      # @return [Object] The inner value of a Some.
+      #
+      # @example
+      #   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?
+
+        value
+      end
+
+      alias present_or_raise present_or_raise!
+
+      # Returns the inner value of a Some, and the given default on a None.
+      # No pedantic type check on the default: this family is deprecated on
+      # Options, and unwrap_or, which the nudge points to, has none either.
+      #
+      # @param default [Object] The value to return on a None.
+      # @return [Object] The inner value of a Some, otherwise the default.
+      #
+      # @example
+      #   Some("secret").present_or("fallback") # => "secret"
+      #   None().present_or("fallback") # => "fallback"
+      def present_or(default)
+        presence_nudge('present_or', 'unwrap_or')
+        return default if none?
+
+        value
+      end
+
+      # Returns the inner value of a Some, and the result of the block on a
+      # None.
+      #
+      # @param block [Proc] The block to call on a None.
+      # @return [Object] The inner value of a Some, otherwise the block's value.
+      #
+      # @example
+      #   Some("secret").present_or_else { "fallback" } # => "secret"
+      #   None().present_or_else { "fallback" } # => "fallback"
+      def present_or_else(&block)
+        presence_nudge('present_or_else', 'unwrap_or_else')
+        return block.call if none?
+
+        value
+      end
+
+      # 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.
+      #
+      # @return [Object, nil] The inner value of a Some, otherwise nil.
+      #
+      # @example
+      #   Some("secret").presence # => "secret"
+      #   None().presence # => nil
+      #   None().presence || "fallback" # => "fallback"
+      def presence
+        presence_nudge('presence', 'unwrap_or(nil)')
+        return nil if none?
+
+        value
+      end
+
+      # @example the blank side of the presence family teaches the combinators
+      #   begin
+      #     None().blank_or("x")
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or(_default)
+        raise_blank_side_teaching(:blank_or)
+      end
+
+      # @example
+      #   begin
+      #     Some(1).blank_or_else { :x }
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or_else(&_block)
+        raise_blank_side_teaching(:blank_or_else)
+      end
+
+      # @example
+      #   begin
+      #     None().blank_or_raise!("msg")
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or_raise!(_message)
+        raise_blank_side_teaching(:blank_or_raise!)
+      end
+
+      alias blank_or_raise blank_or_raise!
+
       # return an Array with the contained value, if any
       # @example
       #   Some(1).to_a # => [1]
@@ -502,6 +610,21 @@ module Errgonomic
         None()
       end
 
+      private
+
+      def presence_nudge(from, to)
+        warn "Errgonomic: `#{from}` on an Option is soft-deprecated; prefer `#{to}`."
+      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

data/lib/errgonomic/rails/active_record_delegate_optional.rb

@@ -9,6 +9,17 @@ module Errgonomic
       extend ActiveSupport::Concern
 
       class_methods do
+        # Names attributes that ActiveRecordOptional must leave alone. It has
+        # to be callable before the include, which is what computes the
+        # wrapped set, so it lives here rather than in the concern itself.
+        def errgonomic_optional_except(*names)
+          @errgonomic_optional_exceptions = errgonomic_optional_exceptions + names.map(&:to_s)
+        end
+
+        def errgonomic_optional_exceptions
+          @errgonomic_optional_exceptions ||= []
+        end
+
         def delegate_optional(*methods, to: nil, prefix: nil, private: nil)
           return if to.nil?
 

data/lib/errgonomic/rails/active_record_optional.rb

@@ -4,9 +4,9 @@ module Errgonomic
   module Rails
     # Concern to make ActiveRecord optional attributes and associations return an Option.
     #
-    # Four pragmatic compromises below satisfy ActiveRecord's assumptions
+    # Five pragmatic compromises below satisfy ActiveRecord's assumptions
     # about how accessors behave. They are deliberate exceptions to "Option
-    # behaves like Rust's Option", and the set is closed: a fifth would be a
+    # behaves like Rust's Option", and the set is closed: a sixth would be a
     # signal that ActiveRecord is pushing back somewhere unmapped, deserving
     # a design discussion rather than a quiet patch.
     #
@@ -15,10 +15,17 @@ module Errgonomic
     #    None() == nil stays false.
     # 2. Some delegates persisted?, marked_for_destruction?, and touch_later
     #    to its record, so a Some can stand in for it during persistence.
-    # 3. Two quoting prepends unwrap Options at the SQL boundary, so an
-    #    Option can be passed to where/quote.
+    # 3. Quoting and predicate-building prepends unwrap Options at the SQL
+    #    boundary, so an Option can be passed to where/quote.
     # 4. SomeValidator provides a presence-style validation for Option
     #    attributes.
+    # 5. Attributes declared with encrypts are never wrapped: ActiveRecord
+    #    Encryption registers a length validator outside Model.validators
+    #    that reads the raw value and cannot survive an Option.
+    #
+    # errgonomic_optional_except is not on the list: it is configuration, an
+    # escape hatch for whatever conflict shows up next, not a semantic
+    # exception.
     module ActiveRecordOptional
       extend ActiveSupport::Concern
 
@@ -27,8 +34,10 @@ module Errgonomic
         optional_associations = reflect_on_all_associations(:belongs_to)
                                 .select { |r| r.options[:optional] }
                                 .map(&:name)
+        excluded = Array(encrypted_attributes).map(&:to_s) + Array(try(:errgonomic_optional_exceptions))
         optional_attributes = column_names
                               .select { |n| column_for_attribute(n).null }
+                              .reject { |n| excluded.include?(n) }
         @errgonomic_optionals = (optional_attributes + optional_associations)
         @errgonomic_optionals.each do |name|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -56,6 +65,23 @@ module Errgonomic
         def errgonomic_optionals
           @errgonomic_optionals
         end
+
+        # Encryption surrounds an attribute with machinery that reads the raw
+        # value, including a length validator that calls to_s on it, so a
+        # wrapped encrypted attribute cannot be saved. Declaring encrypts
+        # after the include is the ordinary spelling, so catch it here too and
+        # give the attribute its plain reader back.
+        def encrypts(*names, **options)
+          super.tap { errgonomic_unwrap_optionals(*names) }
+        end
+
+        def errgonomic_unwrap_optionals(*names)
+          names.map(&:to_s).each do |name|
+            next unless @errgonomic_optionals&.delete(name)
+
+            remove_method(name)
+          end
+        end
       end
     end
   end
@@ -136,3 +162,33 @@ module Errgonomic
 end
 
 ActiveRecord::ConnectionAdapters::Quoting.prepend(Errgonomic::Rails::ActiveRecordQuoting)
+
+module Errgonomic
+  module Rails
+    # A hash condition never reaches the quoting layer as its raw value: the
+    # predicate builder hands it to a bind attribute, which serializes it
+    # through the column type and casts an unrecognized object to nil. Unwrap
+    # one step earlier, where every hash condition passes, so a Some binds as
+    # its inner value and a None as nil, which Arel renders as IS NULL.
+    module ActiveRecordPredicateBuilder
+      def build(attribute, value, *args)
+        super(attribute, Errgonomic::Rails.unwrap_options(value), *args)
+      end
+    end
+
+    # Unwrap Options in a query condition, reaching one level into an array
+    # so a list of Options binds like a list of values.
+    def self.unwrap_options(value)
+      case value
+      when Errgonomic::Option::Any
+        value.unwrap_or(nil)
+      when Array
+        value.any? { |v| v.is_a?(Errgonomic::Option::Any) } ? value.map { |v| unwrap_options(v) } : value
+      else
+        value
+      end
+    end
+  end
+end
+
+ActiveRecord::PredicateBuilder.prepend(Errgonomic::Rails::ActiveRecordPredicateBuilder)

data/lib/errgonomic/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Nick Zadrozny
 bindir: exe
 cert_chain: []
-date: 1980-01-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby