errgonomic 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c579e542517b446e381c09ef98e24237e8ba5c02ca19633d762195d9bcab6a1d
-  data.tar.gz: aa72fb5647fbd9f335bde9b0d10e6a07b68359a7581c4f9152fbf59958d54f43
+  metadata.gz: 6cfa38b0fc666fade921ea48c1301cc51643175a59e82b4f2c50ac3a471e6696
+  data.tar.gz: 8294913794e216f90443e3396753a537d1fbbede4bf6e5eab459bdea51691e6e
 SHA512:
-  metadata.gz: 6423f7d1dbf8a9b0d0ee116f72f7dcd427da888f2213c5ea55ebb13fa7abcec83c63d1897f253a6f644094dabf194c9711f99565bedca9444126951ae715c39e
-  data.tar.gz: 4d3329007ccb658b05cbb4103395133a2c355e4224f5b58850e3da399338ede381bcb0b4db3a2dcb08db54868405d8886e168b1e1b67435e484e9a94e2832f94
+  metadata.gz: 395971235a600af1c734db4dddb9aa8363e63d76ce65175ccb40c358e67aeb48e16379b0682177c42ec4f5d90a50fa14a55f7e7b994b0cd8ffe88dda7f89e688
+  data.tar.gz: d02c232ea2f79a5a3a04ce3913c1e9c07909655da06b11a5654699be7e371f5a5f8345b5efb9a3be8b40e5de667280b59c49dd2ba9541555faef7ccce8b1ca19

data/.rubocop.yml

@@ -18,6 +18,7 @@ Metrics/ClassLength:
   Exclude:
     - lib/errgonomic/option.rb
     - lib/errgonomic/result.rb
+    - test/**/*
 
 # core_ext vendors ActiveSupport's blank?/present? patches; the reopened core
 # classes there are explained by the file header, not per class. Test
@@ -26,3 +27,23 @@ Style/Documentation:
   Exclude:
     - lib/errgonomic/core_ext/**/*
     - test/**/*
+
+# A test states one behavior end to end, and splitting one to satisfy a size
+# metric hides the behavior it was written to name. A cop that names its own
+# Exclude replaces this one, so Metrics/ClassLength repeats the path above.
+Metrics:
+  Exclude:
+    - test/**/*
+
+# The ActiveRecord hooks in the optional concern are one subject — where a
+# reader may come from and what leaves it alone — and reading them together is
+# the point. The generated reader is a heredoc, which the length cops count as
+# if it were code.
+Metrics/BlockLength:
+  Exclude:
+    - lib/errgonomic/rails/active_record_optional.rb
+    - test/**/*
+Metrics/MethodLength:
+  Exclude:
+    - lib/errgonomic/rails/active_record_optional.rb
+    - test/**/*

data/README.md

@@ -107,7 +107,7 @@ in Errgonomic::Option::None
 end
 ```
 
-An unhandled Option refuses to leak into your output: `to_s` and `to_json` raise `Errgonomic::SerializeError`, so you handle the inner value deliberately rather than shipping `#<Errgonomic::Option::Some...>` to a user.
+An unhandled Option refuses to leak into your output: `to_s`, `to_json`, and `as_json` raise `Errgonomic::SerializeError`, so you handle the inner value deliberately rather than shipping `#<Errgonomic::Option::Some...>` to a user. The refusal covers `as_json` because Hash and Array serialization recurses through that method, and an Option nested in a payload would otherwise serialize as `{"value": ...}`.
 
 `unwrap!` and `expect!` are for tests and consoles, not application code: they raise on `None`, which is exactly the ambiguous failure the type exists to prevent. Application code should always have a combinator or pattern match that handles the `None` branch explicitly; if none fits, that is a gap worth an issue rather than a reason to unwrap.
 
@@ -148,7 +148,7 @@ in Errgonomic::Result::Err, Exception => e
 end
 ```
 
-Like Options, unwrapped Results refuse `to_s` and `to_json`. And `Object#result?` / `Object#assert_result!` help enforce at runtime that a value is a Result.
+Like Options, unwrapped Results refuse `to_s`, `to_json`, and `as_json`. And `Object#result?` / `Object#assert_result!` help enforce at runtime that a value is a Result.
 
 ### Optional collections
 
@@ -201,7 +201,7 @@ 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. 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.
+- `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. Three kinds of reader stay unwrapped: attributes declared with `encrypts` and singular associations with `accepts_nested_attributes_for`, both of which ActiveRecord's own machinery reads raw, and anything named by `errgonomic_optional_except`.
 
 ```ruby
 class Credential < ApplicationRecord
@@ -209,8 +209,48 @@ class Credential < ApplicationRecord
   include Errgonomic::Rails::ActiveRecordOptional
 
   encrypts :access_secret   # also left unwrapped, declared either side of the include
+  has_one :rotation_schedule # wrapped: Some(schedule) or None()
+  has_one :owner, required: true # left unwrapped: absence is a validation failure
 end
 ```
+
+**Where the include goes.** A model that includes the concern converts itself, and only itself. The include may sit at the top of the model with the other concerns, which is where Rails convention puts one. An `optional: true` association declared below it is wrapped as it is declared, rather than only the associations the class happened to declare above it.
+
+```ruby
+class Book < ApplicationRecord
+  include Errgonomic::Rails::ActiveRecordOptional
+
+  belongs_to :author, optional: true   # Some(author) or None()
+end
+```
+
+On an application's own base class, the same include reaches every model below it, and no model mentions errgonomic again:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  include Errgonomic::Rails::ActiveRecordOptional
+end
+```
+
+Converting one model or all of them is therefore where the include goes, not a setting to choose. The association macros wrap as each model declares them, and a model's nullable columns are wrapped when ActiveRecord loads its schema, so no class body needs a database while it loads.
+
+An application's own base class is the useful place for it. Engine and gem models such as `ActiveStorage::Blob` and `PaperTrail::Version` descend straight from `ActiveRecord::Base`, and their own code reads their attributes knowing nothing about an Option. Including it on `ActiveRecord::Base` reaches those too, which is rarely what anyone wants.
+
+Two ways out, both readable in a model with no include of its own to point at:
+
+```ruby
+class LegacyImport < ApplicationRecord
+  errgonomic_optional_off                     # this model keeps value-or-nil throughout
+end
+
+class Credential < ApplicationRecord
+  errgonomic_optional_except :legacy_token    # this attribute does
+end
+```
+
+`Model.errgonomic_optionals` reports which readers a model wrapped, which is how to check that a conversion did what it meant to.
+
 - `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()`).

data/lib/errgonomic/option.rb

@@ -556,6 +556,15 @@ module Errgonomic
         raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
       end
 
+      # ActiveSupport's Hash#as_json and Array#as_json recurse through their
+      # members with as_json rather than to_json, so an Option nested in a
+      # payload reaches Object#as_json and serializes as its instance
+      # variables. Refuse there too, and the guard holds wherever an Option
+      # travels.
+      def as_json(*_args)
+        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
+      end
+
       # pp uses its own object dump unless told otherwise; keep it consistent
       # with inspect.
       def pretty_print(pp)

data/lib/errgonomic/rails/active_record_delegate_optional.rb

@@ -9,15 +9,20 @@ 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.
+        # Names attributes that ActiveRecordOptional must leave alone. It has to
+        # be callable before the include, which is what starts the wrapping for
+        # a model that converts itself, so it lives here rather than in the
+        # concern. Where the concern is included on a base class there is no
+        # before, so it also takes back a reader already wrapped.
         def errgonomic_optional_except(*names)
           @errgonomic_optional_exceptions = errgonomic_optional_exceptions + names.map(&:to_s)
+          errgonomic_unwrap_optionals(*names) if respond_to?(:errgonomic_unwrap_optionals)
+          @errgonomic_optional_exceptions
         end
 
         def errgonomic_optional_exceptions
-          @errgonomic_optional_exceptions ||= []
+          @errgonomic_optional_exceptions ||=
+            superclass.respond_to?(:errgonomic_optional_exceptions) ? superclass.errgonomic_optional_exceptions.dup : []
         end
 
         def delegate_optional(*methods, to: nil, prefix: nil, private: nil)

data/lib/errgonomic/rails/active_record_optional.rb

@@ -19,9 +19,11 @@ module Errgonomic
     #    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.
+    # 5. Readers that ActiveRecord's own machinery reads raw are never
+    #    wrapped: an attribute declared with encrypts, whose length validator
+    #    sits outside Model.validators and calls to_s on the value, and a
+    #    singular association with nested attributes, which are assigned
+    #    through the reader and ask the value whether it is a new record.
     #
     # errgonomic_optional_except is not on the list: it is configuration, an
     # escape hatch for whatever conflict shows up next, not a semantic
@@ -30,58 +32,167 @@ module Errgonomic
       extend ActiveSupport::Concern
 
       included do
-        # ::Rails.logger.debug('ActiveRecordOptional')
-        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
-            def #{name}
-              reads = Thread.current[:errgonomic_optional_reads] ||= {}
-              key = [object_id, :#{name}]
-              if reads[key]
-                raise Errgonomic::RecursiveOptionalReadError,
-                      "\#{self.class}##{name} re-entered itself; something beneath this reader reads it again"
-              end
-
-              reads[key] = true
-              begin
-                val = super
-              ensure
-                reads.delete(key)
-              end
-              val.nil? ? Errgonomic::Option::None.new : Errgonomic::Option::Some.new(val)
-            end
-          RUBY
-        end
+        reflect_on_all_associations(:belongs_to)
+          .select { |r| r.options[:optional] }
+          .each { |r| errgonomic_wrap_optional(r.name) }
+        reflect_on_all_associations(:has_one)
+          .reject { |r| r.options[:required] }
+          .each { |r| errgonomic_wrap_optional(r.name) }
       end
 
       class_methods do
+        # What a model wrapped is the signal that a conversion did what it
+        # meant to, and the columns are not wrapped until the schema loads, so
+        # asking loads it.
         def errgonomic_optionals
-          @errgonomic_optionals
+          load_schema
+          errgonomic_optional_names
+        end
+
+        # The set as it stands, for the wrapping itself: reaching for the
+        # schema from here would ask the schema to load while it is loading.
+        def errgonomic_optional_names
+          @errgonomic_optional_names ||= []
+        end
+
+        # Read when a reader is about to be wrapped rather than snapshotted at
+        # include time, so an exclusion works on either side of the include.
+        # That is what an include on a base class needs: there is no "before"
+        # for a model to declare anything in.
+        def errgonomic_optional_exclusions
+          inherited = if superclass.respond_to?(:errgonomic_optional_exclusions)
+                        superclass.errgonomic_optional_exclusions
+                      else
+                        []
+                      end
+
+          inherited |
+            Array(encrypted_attributes).map(&:to_s) |
+            Array(try(:errgonomic_optional_exceptions)).map(&:to_s) |
+            errgonomic_nested_attribute_associations
+        end
+
+        # A model that keeps value-or-nil throughout, for whatever the
+        # application knows about it that the concern does not. Where the
+        # concern is included on a base class, this is how a model leaves.
+        def errgonomic_optional_off
+          @errgonomic_optional_off = true
+          errgonomic_unwrap_optionals(*errgonomic_optional_names.dup)
+        end
+
+        def errgonomic_optional_off?
+          return true if defined?(@errgonomic_optional_off) && @errgonomic_optional_off
+
+          superclass.respond_to?(:errgonomic_optional_off?) && superclass.errgonomic_optional_off?
+        end
+
+        # A reader wrapped by an ancestor is already an Option; a subclass
+        # that wrapped it again would nest it.
+        def errgonomic_optional?(name)
+          return true if errgonomic_optional_names.include?(name)
+
+          superclass.respond_to?(:errgonomic_optional?) && superclass.errgonomic_optional?(name)
+        end
+
+        # ActiveRecord defines its attribute methods the first time a model
+        # needs its schema, not when the class body runs. Wrapping nullable
+        # columns from the same seam keeps a database out of class loading.
+        def load_schema!
+          super
+          errgonomic_wrap_nullable_columns
+        end
+
+        # A subclass loads its own schema, so whichever of the two is touched
+        # first wraps the shared columns first, and a subclass that got there
+        # first would wrap its parent's readers a second time. Walk the chain
+        # from the top down instead, so an ancestor's readers always exist
+        # before a subclass considers the same name.
+        def errgonomic_wrap_nullable_columns
+          superclass.errgonomic_wrap_nullable_columns if superclass.respond_to?(:errgonomic_wrap_nullable_columns)
+          # An abstract class has no table, and asking one for its columns
+          # raises. The concern belongs on an abstract class all the same: that
+          # is where an application puts behaviour every model should have.
+          return if abstract_class? || table_name.nil?
+
+          column_names.each { |name| errgonomic_wrap_optional(name) if column_for_attribute(name).null }
+        end
+
+        # A concern belongs at the top of a model, above its associations, so
+        # an optional belongs_to is routinely declared after the include.
+        # Wrap it when it arrives, or the conversion is silently partial.
+        def belongs_to(name, scope = nil, **options)
+          super.tap { errgonomic_wrap_optional(name) if options[:optional] }
+        end
+
+        # A has_one is absent whenever no row points back at the record, so
+        # its reader carries the same absence a nullable column does.
+        # required: true is the exception: it asserts the record is there, and
+        # absence is a validation failure rather than a value to handle.
+        def has_one(name, scope = nil, **options)
+          super.tap { errgonomic_wrap_optional(name) unless options[:required] }
+        end
+
+        # Nested attributes are assigned through the public reader, and
+        # ActiveRecord asks whatever it finds there whether it is a new
+        # record. An absent association has to arrive as nil for that, so a
+        # singular association with nested attributes keeps its plain reader.
+        def accepts_nested_attributes_for(*names, **options)
+          super.tap { errgonomic_unwrap_optionals(*names) }
+        end
+
+        # ActiveRecord keeps its own register of these, so the exclusion can be
+        # read from there rather than recorded as it goes past.
+        def errgonomic_nested_attribute_associations
+          return [] unless respond_to?(:nested_attributes_options)
+
+          nested_attributes_options.keys.map(&:to_s).select do |name|
+            %i[has_one belongs_to].include?(reflect_on_association(name)&.macro)
+          end
         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.
+        # after the include is the ordinary spelling, and the exclusion is read
+        # from ActiveRecord's own register when a reader is about to be
+        # wrapped, so this only has to take back a reader already wrapped.
         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)
+            next unless errgonomic_optional_names.delete(name)
 
             remove_method(name)
           end
         end
+
+        def errgonomic_wrap_optional(name)
+          name = name.to_s
+          return if errgonomic_optional_off?
+          return if errgonomic_optional_exclusions.include?(name) || errgonomic_optional?(name)
+
+          errgonomic_optional_names << name
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              reads = Thread.current[:errgonomic_optional_reads] ||= {}
+              key = [object_id, :#{name}]
+              if reads[key]
+                raise Errgonomic::RecursiveOptionalReadError,
+                      "\#{self.class}##{name} re-entered itself; something beneath this reader reads it again"
+              end
+
+              reads[key] = true
+              begin
+                val = super
+              ensure
+                reads.delete(key)
+              end
+              val.nil? ? Errgonomic::Option::None.new : Errgonomic::Option::Some.new(val)
+            end
+          RUBY
+        end
       end
     end
   end
@@ -146,6 +257,18 @@ class Object
   end
 end
 
+module Errgonomic
+  module Option
+    # An Option is already lifted. Lifting it again would nest it, and the
+    # nesting is invisible until something reaches for the inner value.
+    class Any
+      def to_option
+        self
+      end
+    end
+  end
+end
+
 module Errgonomic
   module Rails
     # Teach ActiveRecord SQL quoting to unwrap Options, quoting a None as

data/lib/errgonomic/result.rb

@@ -369,6 +369,15 @@ module Errgonomic
         raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Result'
       end
 
+      # ActiveSupport's Hash#as_json and Array#as_json recurse through their
+      # members with as_json rather than to_json, so a Result nested in a
+      # payload reaches Object#as_json and serializes as its instance
+      # variables. Refuse there too, and the guard holds wherever a Result
+      # travels.
+      def as_json(*_args)
+        raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Result'
+      end
+
       # pp uses its own object dump unless told otherwise; keep it consistent
       # with inspect.
       def pretty_print(pp)

data/lib/errgonomic/version.rb

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

metadata

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