attr_json 1.5.0 → 2.0.0.rc1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: attr_json
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0.rc1
 platform: ruby
 authors:
 - Jonathan Rochkind
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-18 00:00:00.000000000 Z
+date: 2023-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 6.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.1'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 6.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.1'
@@ -130,8 +130,8 @@ dependencies:
         version: '1.0'
 description: |-
   ActiveRecord attributes stored serialized in a json column, super smooth.
-  For Rails 5.0, 5.1, or 5.2. Typed and cast like Active Record. Supporting nested models,
-  dirty tracking, some querying (with postgres jsonb contains), and working smoothy with form builders.
+  Typed and cast like Active Record. Supporting nested models, dirty tracking, some querying
+  (with postgres jsonb contains), and working smoothy with form builders.
 
   Use your database as a typed object store via ActiveRecord, in the same models right next to
   ordinary ActiveRecord column-backed attributes and associations. Your json-serialized attr_json
@@ -159,12 +159,8 @@ files:
 - bin/rspec
 - bin/setup
 - config.ru
-- doc_src/dirty_tracking.md
 - doc_src/forms.md
 - gemfiles/.bundle/config
-- gemfiles/rails_5_0.gemfile
-- gemfiles/rails_5_1.gemfile
-- gemfiles/rails_5_2.gemfile
 - gemfiles/rails_6_0.gemfile
 - gemfiles/rails_6_1.gemfile
 - gemfiles/rails_7_0.gemfile
@@ -180,7 +176,6 @@ files:
 - lib/attr_json/nested_attributes/multiparameter_attribute_writer.rb
 - lib/attr_json/nested_attributes/writer.rb
 - lib/attr_json/record.rb
-- lib/attr_json/record/dirty.rb
 - lib/attr_json/record/query_builder.rb
 - lib/attr_json/record/query_scopes.rb
 - lib/attr_json/serialization_coder_from_type.rb
@@ -204,12 +199,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.33
 signing_key:

data/doc_src/dirty_tracking.md

@@ -1,155 +0,0 @@
-# Dirty Tracking Support in AttrJson
-
-In ordinary ActiveRecord, there is dirty/change-tracking support for attributes,
-that lets you see what changes currently exist in the model compared to what
-was fetched from the db, as well as what changed on the most recent save operation.
-
-```ruby
-model = SomeModel.new
-model.str_value = "some value"
-model.changes_to_save
-  # => { 'str_value' => 'some_value'}
-model.will_save_change_to_str_value?
-  # => true
-model.save
-model.saved_changes
-  # => { 'str_value' => 'some_value'}
-model.str_value_before_last_save
-  # => nil
-# and more
-```
-
-You may be used to an older style of AR change-tracking methods,
-involving `changes` and `previous_changes`. These older-style methods were
-deprecated in Rails 5.1 and removed in Rails 5.2.  It's a bit confusing and not
-fully documented in AR, see more at
-[these](https://www.levups.com/en/blog/2017/undocumented-dirty-attributes-activerecord-changes-rails51.html)
-blog [posts](https://www.ombulabs.com/blog/rails/upgrades/active-record-5-1-api-changes.html),
-and the initial [AR pull request](https://github.com/rails/rails/pull/25337).
-
-AttrJson supports all of these new-style dirty-tracking methods, only
-in Rails 5.1+. (*Sorry, our dirty tracking support does not work with Rails 5.0,
-or old-style dirty API in Rails 5.1. Only new-style API in Rails 5.1+*). I wasn't
-able to find a good way to get changes in the default Rails dirty tracking methods,
-so instead **they are available off a separate `attr_json_changes` method**,
-which also allows customization of if host record changes are also included.
-
-To include the AttrJson dirty-tracking features, include the
-`AttrJson::Record::Dirty` module in your active record model already including
-`AttrJson::Record`:
-
-```ruby
-class MyEmbeddedModel
-  include AttrJson::Model
-
-  attr_json :str, :string
-end
-
-class MyModel < ActiveRecord::Base
-  include AttrJson::Record
-  include AttrJson::Record::Dirty
-
-  attr_json :str, :string
-  attr_json :str_array, :string, array: true
-  attr_json :array_of_models, MyEmbeddedModel.to_type, array: true
-end
-```
-
-Now dirty changes are available off a `attr_json_changes` method.
-The full suite of (new, Rails 5.1+) ActiveRecord dirty methods are supported,
-both ones that take the attribute-name as an argument, and synthetic attribute-specific
-methods. All top-level `attr_json`s are supported, including those that
-include arrays and/or complex/nested/compound models.
-
-```ruby
-model = MyModel.new
-model.str = "some value"
-model.attr_json_changes.will_save_change_to_str? #=> true
-model.str_array = ["original1", "original2"]
-model.array_of_models = [MyEmbeddedModel.new(str: "value")]
-model.save
-
-model.attr_json_changes.saved_changes
-  # => {"str"=>[nil, "some value"], "str_array"=>[nil, ["original1", "original2"]], "array_of_models"=>[nil, [#<MyEmbeddedModel:0x00007fb285d12330 @attributes={"str"=>"value"}, @validation_context=nil, @errors=#<ActiveModel::Errors:0x00007fb285d00400 @base=#<MyEmbeddedModel:0x00007fb285d12330 ...>, @messages={}, @details={}>>]]
-
-model.str_array << "new1"
-
-model.attr_json_changes.will_save_change_to_str_array? # => true
-model.attr_json_changes.str_array_change_to_be_saved
-  # => [["original1", "original2"], ["original1", "original2", "new1"]]
-```
-
-## Cast representation vs Json representation
-
-If you ask to see changes, you are going to see the changes reported as _cast_ values,
-not _json_ values. For instance, you'll see your actual `AttrJson::Model`
-objects instead of the hashes they serialize to, and ruby DateTime objects instead
-of the ISO 8601 strings they serialize to.
-
-If you'd like to see the the JSON-compat data structures instead, just tag
-on the `as_json` modifier. For simple strings and ints and similar primitives,
-it won't make a difference, for some types it will:
-
-```ruby
-model.attr_json_changes.changes_to_save
-#=> {
-#  json_str: [nil, "some value"]
-#  embedded_model: [nil, #<TestModel:0x00007fee25a04bf8 @attributes={"str"=>"foo"}>]
-#  json_date: [nil, {{ruby Date object}}]
-# }
-
-model.attr_json_changes.as_json.changes_to_save
-#=> {
-#  json_str: [nil, "some_value"]
-#  embedded_model: [nil, {'str' => 'foo'}]
-#  json_date: [nil, "2018-03-23"]
-# }
-
-```
-
-All existing values are serialized every time you call this, since they are stored
-in cast form internally. So there _could_ be perf implications, but generally it is looking fine.
-
-## Merge in ordinary AR attribute dirty tracking
-
-Now you have one place to track 'ordinary' AR attribute "dirtyness"
-(`model.some_attribute_will_change?`), and another place to track attr_json
-dirty-ness (`my_model.attr_json_changes.some_json_attr_will_change?`).
-
-You may wish you could have one place that tracked both, so your calling code
-doesn't need to care if a given attribute is jsonb-backed or ordinary-column, and
-is resilient if an attribute switches from one to another.
-
-While we couldn't get this on the built-in dirty attributes, you *can* optionally
-tell the `attr_json_changes` to include 'ordinary' changes from model too,
-all in one place, by adding on the method `merged`.
-
-```ruby
-model.attr_json_changes.merged.ordinary_attribute_will_change?
-model.attr_json_changes.merged.attr_json_will_change?
-model.attr_json_changes.merged.attr_json_will_change?
-model.attr_json_changes.merged.changes_to_save
-# => includes a hash with keys that are both ordinary AR attributes
-#    and attr_jsons, as applicable for changes.
-```
-
-This will ordinarily include your json container attributes (eg `json_attributes`)
-too, as they will show up in ordinary AR dirty tracking since they are just AR
-columns.
-
-If you'd like to exclude these from the merged dirty tracking, pretend the json
-container attributes don't exist and just focus on the individual `attr_json`s,
-we got you covered:
-
-```ruby
-model.attr_json_changes.merged(containers: false).attr_jsons_will_change?
-  # => always returns `nil`, the 'real' `attr_jsons` attribute is dead to us.
-```
-
-## Combine both of these modifiers at once no problem
-
-```ruby
-model.attr_json_changes.as_json.merged.saved_changes
-model.attr_json_changes.as_json.merged(containers: false).saved_changes
-model.attr_json_changes.merged(containers: true).as_json.saved_changes
-```

data/gemfiles/rails_5_0.gemfile

@@ -1,20 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "combustion", "~> 0.9.0"
-gem "rails", "~> 5.0.0"
-gem "pg", "~> 0.18"
-gem "rspec-rails", "~> 4.0"
-gem "simple_form", ">= 4.0"
-gem "cocoon", ">= 1.2"
-gem "jquery-rails"
-gem "coffee-rails"
-gem "sprockets-rails"
-gem "capybara", "~> 3.0"
-gem "webdrivers", "~> 4.0"
-gem "selenium-webdriver"
-gem "byebug"
-gem "rails-ujs", require: false
-
-gemspec path: "../"

data/gemfiles/rails_5_1.gemfile

@@ -1,19 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "combustion", "~> 0.9.0"
-gem "rails", "~> 5.1.0"
-gem "pg", "~> 1.0"
-gem "rspec-rails", "~> 4.0"
-gem "simple_form", ">= 4.0"
-gem "cocoon", ">= 1.2"
-gem "jquery-rails"
-gem "coffee-rails"
-gem "sprockets-rails"
-gem "capybara", "~> 3.0"
-gem "webdrivers", "~> 4.0"
-gem "selenium-webdriver"
-gem "byebug"
-
-gemspec path: "../"

data/gemfiles/rails_5_2.gemfile

@@ -1,19 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "combustion", "~> 0.9.0"
-gem "rails", "~> 5.2.0"
-gem "pg", "~> 1.0"
-gem "rspec-rails", "~> 4.0"
-gem "simple_form", ">= 4.0"
-gem "cocoon", ">= 1.2"
-gem "jquery-rails"
-gem "coffee-rails"
-gem "sprockets-rails"
-gem "capybara", "~> 3.0"
-gem "webdrivers", "~> 4.0"
-gem "selenium-webdriver"
-gem "byebug"
-
-gemspec path: "../"

data/lib/attr_json/record/dirty.rb

@@ -1,287 +0,0 @@
-module AttrJson
-  module Record
-    # This only works in Rails 5.1+, and only uses the 'new style' dirty
-    # tracking methods, available in Rails 5.1+.
-    #
-    # Add into an ActiveRecord object with AttrJson::Record,
-    # to track dirty changes to attr_jsons, off the attr_json_changes
-    # object.
-    #
-    #     some_model.attr_json_changes.saved_changes
-    #     some_model.attr_json_changes.json_attr_before_last_save
-    #
-    # All methods ordinarily in ActiveRecord::Attributes::Dirty should be available,
-    # including synthetic attribute-specific ones like `will_save_change_to_attribute_name?`.
-    # By default, they _only_ report changes from json attributes.
-    # To have a merged list also including ordinary AR changes, add on `merged`:
-    #
-    #     some_model.attr_json_changes.merged.saved_changes
-    #     some_model.attr_json_changes.merged.ordinary_attr_before_last_save
-    #
-    # Complex nested models will show up in changes as the cast models. If you want
-    # the raw json instead, use `as_json`:
-    #
-    #     some_model.attr_json_changes.as_json.saved_changes
-    #
-    # You can combine as_json and merged if you like:
-    #
-    #     some_model.attr_json_changes.as_json.merged.saved_changes
-    #
-    # See more in [separate documentation guide](../../../doc_src/dirty_tracking.md)
-    #
-    # See what methods are available off of the object returned by {attr_json_changes}
-    # in {Dirty::Implementation} -- should be the AR dirty-tracking methods you expect.
-    module Dirty
-      def attr_json_changes
-        Implementation.new(self)
-      end
-
-
-      class Implementation
-        # The attribute_method stuff is copied from ActiveRecord::Dirty,
-        # to give you all the same synthetic per-attribute methods.
-        # We make it work with overridden #matched_attribute_method below.
-        include ActiveModel::AttributeMethods
-
-        # Attribute methods for "changed in last call to save?"
-        attribute_method_affix(prefix: "saved_change_to_", suffix: "?")
-        attribute_method_prefix("saved_change_to_")
-        attribute_method_suffix("_before_last_save")
-
-        # Attribute methods for "will change if I call save?"
-        attribute_method_affix(prefix: "will_save_change_to_", suffix: "?")
-        attribute_method_suffix("_change_to_be_saved", "_in_database")
-
-        attr_reader :model
-
-        def initialize(model, merged: false, merge_containers: false, as_json: false)
-          @model = model
-          @merged = !!merged
-          @merge_containers = !!merge_containers
-          @as_json = !!as_json
-        end
-
-        # return a copy with `merged` attribute true, so dirty tracking
-        # will include ordinary AR attributes too, and you can do things like:
-        #
-        #     model.attr_json_changes.merged.saved_change_to_attribute?(ordinary_or_attr_json)
-        #
-        # By default, the json container attributes are included too. If you
-        # instead want our dirty tracking to pretend they don't exist:
-        #
-        #     model.attr_json_changes.merged(containers: false).etc
-        #
-        def merged(containers: true)
-          self.class.new(model, merged: true, merge_containers: containers,
-            as_json: as_json?)
-        end
-
-        # return a copy with as_json parameter set to true, so change diffs
-        # will be the json structures serialized, not the cast models.
-        # for 'primitive' types will be the same, but for AttrJson::Models
-        # very different.
-        def as_json
-          self.class.new(model, as_json: true,
-            merged: merged?,
-            merge_containers: merge_containers?)
-        end
-
-        # should we handle ordinary AR attributes too in one merged
-        # change tracker?
-        def merged?
-          @merged
-        end
-
-        # if we're `merged?` and `merge_containers?` is **false**, we
-        # _omit_ our json container attributes from our dirty tracking.
-        # only has meaning if `merged?` is true. Defaults to true.
-        def merge_containers?
-          @merge_containers
-        end
-
-        def as_json?
-          @as_json
-        end
-
-
-        def saved_change_to_attribute(attr_name)
-          attribute_def = registry[attr_name.to_sym]
-          if ! attribute_def
-            if merged? && (merge_containers? || ! registry.container_attributes.include?(attr_name.to_s))
-              return model.saved_change_to_attribute(attr_name)
-            else
-              return nil
-            end
-          end
-
-          json_container = attribute_def.container_attribute
-
-          (before_container, after_container) = model.saved_change_to_attribute(json_container)
-
-          formatted_before_after(
-            before_container.try(:[], attribute_def.store_key),
-            after_container.try(:[], attribute_def.store_key),
-            attribute_def)
-        end
-
-        def attribute_before_last_save(attr_name)
-          saved_change = saved_change_to_attribute(attr_name)
-          return nil if saved_change.nil?
-
-          saved_change[0]
-        end
-
-        def saved_change_to_attribute?(attr_name)
-          return nil unless registry[attr_name.to_sym] || merged? && (merge_containers? || ! registry.container_attributes.include?(attr_name.to_s))
-          ! saved_change_to_attribute(attr_name).nil?
-        end
-
-        def saved_changes
-          original_saved_changes = model.saved_changes
-          return {} if original_saved_changes.blank?
-
-          json_attr_changes = registry.definitions.collect do |definition|
-            if container_change = original_saved_changes[definition.container_attribute]
-              old_v = container_change.dig(0, definition.store_key)
-              new_v = container_change.dig(1, definition.store_key)
-              if old_v != new_v
-                [ definition.name.to_s, formatted_before_after(old_v, new_v, definition) ]
-              end
-            end
-          end.compact.to_h
-
-          prepared_changes(json_attr_changes, original_saved_changes)
-        end
-
-        def saved_changes?
-          saved_changes.present?
-        end
-
-
-        def attribute_in_database(attr_name)
-          to_be_saved = attribute_change_to_be_saved(attr_name)
-          if to_be_saved.nil?
-            if merged? && (merge_containers? || ! registry.container_attributes.include?(attr_name.to_s))
-              return model.attribute_change_to_be_saved(attr_name)
-            else
-              return nil
-            end
-          end
-
-          to_be_saved[0]
-        end
-
-        def attribute_change_to_be_saved(attr_name)
-          attribute_def = registry[attr_name.to_sym]
-          if ! attribute_def
-            if merged? && (merge_containers? || ! registry.container_attributes.include?(attr_name.to_s))
-              return model.attribute_change_to_be_saved(attr_name)
-            else
-              return nil
-            end
-          end
-
-          json_container = attribute_def.container_attribute
-
-          (before_container, after_container) = model.attribute_change_to_be_saved(json_container)
-
-          formatted_before_after(
-            before_container.try(:[], attribute_def.store_key),
-            after_container.try(:[], attribute_def.store_key),
-            attribute_def
-          )
-        end
-
-        def will_save_change_to_attribute?(attr_name)
-          return nil unless registry[attr_name.to_sym] || merged? && (merge_containers? || ! registry.container_attributes.include?(attr_name.to_s))
-          ! attribute_change_to_be_saved(attr_name).nil?
-        end
-
-        def changes_to_save
-          original_changes_to_save = model.changes_to_save
-
-          return {} if original_changes_to_save.blank?
-
-          json_attr_changes = registry.definitions.collect do |definition|
-            if container_change = original_changes_to_save[definition.container_attribute]
-              old_v = container_change.dig(0, definition.store_key)
-              new_v = container_change.dig(1, definition.store_key)
-              if old_v != new_v
-                [ definition.name.to_s, formatted_before_after(old_v, new_v, definition) ]
-              end
-            end
-          end.compact.to_h
-
-          prepared_changes(json_attr_changes, original_changes_to_save)
-        end
-
-        def has_changes_to_save?
-          changes_to_save.present?
-        end
-
-        def changed_attribute_names_to_save
-          changes_to_save.keys
-        end
-
-        def attributes_in_database
-          changes_to_save.transform_values(&:first)
-        end
-
-        private
-
-        # returns an array of before and after, possibly formatted with as_json.
-        # if both before and after are nil, returns nil.
-        def formatted_before_after(before_v, after_v, attribute_def)
-          return nil if before_v.nil? && after_v.nil?
-
-          if as_json?
-            before_v = attribute_def.type.serialize(before_v) unless before_v.nil?
-            after_v = attribute_def.type.serialize(after_v) unless after_v.nil?
-          end
-
-          [
-            before_v,
-            after_v
-          ]
-
-        end
-
-        # Takes a hash of _our_ attr_json changes, and possibly
-        # merges them into the hash of all changes from the parent record,
-        # depending on values of `merged?` and `merge_containers?`.
-        def prepared_changes(json_attr_changes, all_changes)
-          if merged?
-            all_changes.merge(json_attr_changes).tap do |merged|
-              unless merge_containers?
-                merged.except!(*registry.container_attributes)
-              end
-            end
-          else
-            json_attr_changes
-          end
-        end
-
-        def registry
-          model.class.attr_json_registry
-        end
-
-        # Override from ActiveModel::AttributeMethods
-        # to not require class-static define_attribute, but instead dynamically
-        # find it from currently declared attributes.
-        # https://github.com/rails/rails/blob/6aa5cf03ea8232180ffbbae4c130b051f813c670/activemodel/lib/active_model/attribute_methods.rb#L463-L468
-        def matched_attribute_method(method_name)
-          if self.class.respond_to?(:attribute_method_patterns_matching, true)
-            # Rails 7.1+
-            matches = self.class.send(:attribute_method_patterns_matching, method_name)
-          else
-            matches = self.class.send(:attribute_method_matchers_matching, method_name)
-          end
-
-          matches.detect do |match|
-            registry.has_attribute?(match.attr_name)
-          end
-        end
-      end
-    end
-  end
-end