Improve Dirty Tracking of Mutable Collection Types

CHANGELOG.md

@@ -1,6 +1,49 @@
 Unreleased Changes
 ------------------
 
+* Feature - Aws::Record::DirtyTracking - Improves dirty tracking by adding
+  support for tracking mutations of attribute value objects. This feature is on
+  by default for the "collection" types: `:list_attr`, `:map_attr`,
+  `:string_set_attr`, and `:numeric_set_attr`.
+
+  Before this feature, the `#save` method's default behavior of running an
+  update call for dirty attributes only could cause problems for users of
+  collection attributes. As many of them are commonly manipulated using mutable
+  state, the underlying "clean" version of the objects would be modified and the
+  updated object would not be recognized as dirty, and therefore would not be
+  updated at all unless explicitly marked as dirty or through a force put.
+
+  ```ruby
+  class Model
+    include Aws::Record
+    string_attr :uuid, hash_key: true
+    list_attr :collection
+  end
+
+  item = Model.new(uuid: SecureRandom.uuid, collection: [1,2,3])
+  item.clean! # As if loaded from the database, to demonstrate the new tracking.
+  item.dirty? # => false
+  item.collection << 4 # In place mutation of the "collection" array.
+  item.dirty? # => true (Previous versions would not recognize this as dirty.
+  item.save # Would call Aws::DynamoDB::Client#update_item for :collection only.
+  ```
+
+  Note that this feature is implemented using deep copies of collection objects
+  in memory, so there is a potential memory/performance hit in exchange for the
+  added accuracy. As such, mutation tracking can be explicitly turned off at the
+  attribute level or at the full model level, if desired.
+
+  ```ruby
+  # Note that the disabling of mutation tracking is redundant in this example,
+  # for illustration purposes.
+  class Model
+    include Aws::Record
+    disable_mutation_tracking # For turning off mutation at the model level.
+    string_attr :uuid, hash_key: true
+    list_attr :collection, mutation_tracking: false # Turn off at attr level.
+  end
+  ```
+
 1.0.0.pre.8 (2016-05-19)
 ------------------
 

lib/aws-record/record.rb

@@ -50,6 +50,7 @@ module Record
     #     # Attribute definitions go here...
     #   end
     def self.included(sub_class)
+      @track_mutations = true
       sub_class.send(:extend, RecordClassMethods)
       sub_class.send(:include, Attributes)
       sub_class.send(:include, ItemOperations)
@@ -183,6 +184,26 @@ def dynamodb_client
         @dynamodb_client ||= configure_client
       end
 
+      # Turns off mutation tracking for all attributes in the model.
+      def disable_mutation_tracking
+        @track_mutations = false
+      end
+
+      # Turns on mutation tracking for all attributes in the model. Note that
+      # mutation tracking is on by default, so you generally would not need to
+      # call this. It is provided in case there is a need to dynamically turn
+      # this feature on and off, though that would be generally discouraged and
+      # could cause inaccurate mutation tracking at runtime.
+      def enable_mutation_tracking
+        @track_mutations = true
+      end
+
+      # @return [Boolean] true if mutation tracking is enabled at the model
+      # level, false otherwise.
+      def mutation_tracking_enabled?
+        @track_mutations == false ? false : true
+      end
+
       private
       def _user_agent(custom)
         if custom

lib/aws-record/record/attribute.rb

@@ -39,11 +39,17 @@ class Attribute
       #   "M", "L". Optional if this attribute will never be used for a key or
       #   secondary index, but most convenience methods for setting attributes
       #   will provide this.
+      # @option options [Boolean] :mutation_tracking Optional attribute used to
+      #   indicate if mutations to values should be explicitly tracked when
+      #   determining if a value is "dirty". Important for collection types
+      #   which are often primarily modified by mutation of a single object
+      #   reference. By default, is false.
       def initialize(name, options = {})
         @name = name
         @database_name = options[:database_attribute_name] || name.to_s
         @dynamodb_type = options[:dynamodb_type]
         @marshaler = options[:marshaler] || DefaultMarshaler
+        @mutation_tracking = options[:mutation_tracking]
       end
 
       # Attempts to type cast a raw value into the attribute's type. This call
@@ -65,6 +71,12 @@ def serialize(raw_value)
         @marshaler.serialize(raw_value)
       end
 
+      # @return [Boolean] true if this attribute should do active mutation
+      #  tracking, false otherwise.
+      def track_mutations?
+        @mutation_tracking ? true : false
+      end
+
       # @api private
       def extract(dynamodb_item)
         dynamodb_item[@database_name]

lib/aws-record/record/attributes.rb

@@ -87,6 +87,11 @@ module ClassMethods
         #   "M", "L". Optional if this attribute will never be used for a key or
         #   secondary index, but most convenience methods for setting attributes
         #   will provide this.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
@@ -118,6 +123,11 @@ def attr(name, marshaler, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def string_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
           attr(name, Attributes::StringMarshaler, opts)
@@ -132,6 +142,11 @@ def string_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def boolean_attr(name, opts = {})
           opts[:dynamodb_type] = "BOOL"
           attr(name, Attributes::BooleanMarshaler, opts)
@@ -146,6 +161,11 @@ def boolean_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def integer_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
           attr(name, Attributes::IntegerMarshaler, opts)
@@ -160,6 +180,11 @@ def integer_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def float_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
           attr(name, Attributes::FloatMarshaler, opts)
@@ -174,6 +199,11 @@ def float_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def date_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
           attr(name, Attributes::DateMarshaler, opts)
@@ -188,6 +218,11 @@ def date_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is false.
         def datetime_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
           attr(name, Attributes::DateTimeMarshaler, opts)
@@ -223,8 +258,14 @@ def datetime_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
         def list_attr(name, opts = {})
           opts[:dynamodb_type] = "L"
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
           attr(name, Attributes::ListMarshaler, opts)
         end
 
@@ -258,8 +299,14 @@ def list_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
         def map_attr(name, opts = {})
           opts[:dynamodb_type] = "M"
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
           attr(name, Attributes::MapMarshaler, opts)
         end
 
@@ -280,8 +327,14 @@ def map_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
         def string_set_attr(name, opts = {})
           opts[:dynamodb_type] = "SS"
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
           attr(name, Attributes::StringSetMarshaler, opts)
         end
 
@@ -302,8 +355,14 @@ def string_set_attr(name, opts = {})
         #   the hash key for the table.
         # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
+        # @option options [Boolean] :mutation_tracking Optional attribute used to
+        #   indicate if mutations to values should be explicitly tracked when
+        #   determining if a value is "dirty". Important for collection types
+        #   which are often primarily modified by mutation of a single object
+        #   reference. By default, is true.
         def numeric_set_attr(name, opts = {})
           opts[:dynamodb_type] = "NS"
+          opts[:mutation_tracking] = true if opts[:mutation_tracking].nil?
           attr(name, Attributes::NumericSetMarshaler, opts)
         end
 
@@ -333,6 +392,13 @@ def keys
           @keys
         end
 
+        # @param [Symbol] attr_sym The symbolized name of the attribute.
+        # @return [Boolean] true if object mutations are tracked for dirty
+        #   checking of that attribute, false if mutations are not tracked.
+        def track_mutations?(attr_sym)
+          mutation_tracking_enabled? && attributes[attr_sym].track_mutations?
+        end
+
         private
         def define_attr_methods(name, attribute)
           define_method(name) do