aws-record 2.7.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f48531ca8b917f680a1d9a5d21afd1611aba0eb96916a5783addaf7939cda8
-  data.tar.gz: 7f6cbb16271455ada17a61f32106800b65d3b4103a5254e7686e06d5cf715cca
+  metadata.gz: 6316b0ad6349fdea29d10e1325b6044b54eb3f2696a9bd1692cc30881e5e2e02
+  data.tar.gz: 57c1d3c37435e3bc79eac488738c08f8ac6536bfbd5f493ac221f248bdf3e8c8
 SHA512:
-  metadata.gz: 5bb474f4d13e469b9af991e061b10a54279f37d7390b9cb1bffafd40d039c649c12ca5423140d4a232a08536ec715df89db2e07f6670ef0242732cbe78d1d890
-  data.tar.gz: 9b61d0d93ce9b657989fefde1201aab35253e656035ffb87ccbebfbafe4ea423883146dd4dec510dfdf5deec74b274784f6490d86804cf76b09aeee58f41cdfb
+  metadata.gz: 8bdca623e0884f5cd2a704bf807be58687077e04f746e5c99a6e15ce2df4ad378afd6e3d6bdb74899d4a86521e921fd588a5fbdc5ba1c6b6c06e3daf08ad3d16
+  data.tar.gz: 2448123077cea61bf1ab263278ce1a2209d69d9a7ed53d8f665feb8bef2c7185c447378f3c4ae70a96a16ef4d62e4d2a3ffd1769f94bc367e8cd2e0c1733c4cd

data/lib/aws-record/record/attributes.rb

@@ -20,8 +20,19 @@ module Aws
         model_attributes = ModelAttributes.new(self)
         sub_class.instance_variable_set("@attributes", model_attributes)
         sub_class.instance_variable_set("@keys", KeyAttributes.new(model_attributes))
+        if Aws::Record.extends_record?(sub_class)
+          inherit_attributes(sub_class)
+        end
       end
 
+      # Base initialization method for a new item. Optionally, allows you to
+      # provide initial attribute values for the model. You do not need to
+      # provide all, or even any, attributes at item creation time.
+      #
+      # === Inheritance Support
+      # Child models will inherit the attributes and keys defined in the parent
+      # model. Child models can override attribute keys if defined in their own model.
+      # See examples below to see the feature in action.
       # @example Usage Example
       #   class MyModel
       #     include Aws::Record
@@ -31,11 +42,34 @@ module Aws
       #   end
       #
       #   item = MyModel.new(id: 1, name: "Quick Create")
+      # @example Child model inheriting from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     string_attr :name,   hash_key: true
+      #     integer_attr :age,   default_value: 1
+      #   end
       #
-      # Base initialization method for a new item. Optionally, allows you to
-      # provide initial attribute values for the model. You do not need to
-      # provide all, or even any, attributes at item creation time.
+      #   class Cat < Animal
+      #     include Aws::Record
+      #     integer_attr :num_of_wiskers
+      #   end
       #
+      #   cat = Cat.find(name: 'Foo')
+      #   cat.age    # => 1
+      #   cat.num_of_wiskers = 200
+      # @example Child model overrides the hash key
+      #   class Animal
+      #     include Aws::Record
+      #     string_attr :name,   hash_key: true
+      #     integer_attr :age,   range_key: true
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #     integer_attr :id, hash_key: true
+      #   end
+      #
+      #   Dog.keys # => {:hash=>:id, :range=>:age}
       # @param [Hash] attr_values Attribute symbol/value pairs for any initial
       #  attribute values you wish to set.
       # @return [Aws::Record] An item instance for your model.
@@ -56,6 +90,27 @@ module Aws
         @data.hash_copy
       end
 
+      private
+      def self.inherit_attributes(klass)
+        superclass_attributes = klass.superclass.instance_variable_get("@attributes")
+
+        superclass_attributes.attributes.each do |name, attribute|
+          subclass_attributes = klass.instance_variable_get("@attributes")
+          subclass_attributes.register_superclass_attribute(name, attribute)
+        end
+
+        superclass_keys = klass.superclass.instance_variable_get("@keys")
+        subclass_keys = klass.instance_variable_get("@keys")
+
+        if superclass_keys.hash_key
+          subclass_keys.hash_key = superclass_keys.hash_key
+        end
+
+        if superclass_keys.range_key
+          subclass_keys.range_key = superclass_keys.range_key
+        end
+      end
+
       module ClassMethods
 
         # Define an attribute for your model, providing your own attribute type.
@@ -382,6 +437,77 @@ module Aws
           attr(name, Marshalers::NumericSetMarshaler.new(opts), opts)
         end
 
+        # Define an atomic counter attribute for your model.
+        #
+        # Atomic counter are an integer-type attribute that is incremented,
+        # unconditionally, without interfering with other write requests.
+        # The numeric value increments each time you call +increment_<attr>!+.
+        # If a specific numeric value are passed in the call, the attribute will
+        # increment by that value.
+        #
+        # To use +increment_<attr>!+ method, the following condition must be true:
+        # * None of the attributes have dirty changes.
+        # * If there is a value passed in, it must be an integer.
+        # For more information, see
+        # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.AtomicCounters Atomic counter}
+        # in the Amazon DynamoDB Developer Guide.
+        #
+        # @param [Symbol] name Name of this attribute.  It should be a name that
+        #   is safe to use as a method.
+        # @param [Hash] opts
+        # @option opts [Object] :default_value Optional attribute used to
+        #   define a "default value" to be used if the attribute's value on an
+        #   item is nil or not set at persistence time. The "default value" of
+        #   the attribute starts at 0.
+        #
+        # @example Usage Example
+        #   class MyRecord
+        #     include Aws::Record
+        #     integer_attr :id, hash_key: true
+        #     atomic_counter :counter
+        #   end
+        #
+        #   record = MyRecord.find(id: 1)
+        #   record.counter #=> 0
+        #   record.increment_counter! #=> 1
+        #   record.increment_counter!(2) #=> 3
+        # @see #attr #attr method for additional hash options.
+        def atomic_counter(name, opts = {})
+          opts[:dynamodb_type] = "N"
+          opts[:default_value] ||= 0
+          attr(name, Marshalers::IntegerMarshaler.new(opts), opts)
+
+          define_method("increment_#{name}!") do |increment=1|
+
+            if dirty?
+              msg = "Attributes need to be saved before atomic counter can be incremented"
+              raise Errors::RecordError, msg
+            end
+
+            unless increment.is_a?(Integer)
+              msg = "expected an Integer value, got #{increment.class}"
+              raise ArgumentError, msg
+            end
+
+            resp = dynamodb_client.update_item({
+              table_name: self.class.table_name,
+              key: key_values,
+              expression_attribute_values: {
+                ":i" => increment
+              },
+              expression_attribute_names: {
+                "#n" => name
+              },
+              update_expression: "SET #n = #n + :i",
+              return_values: "UPDATED_NEW"
+            })
+            assign_attributes(resp[:attributes])
+            @data.clean!
+            @data.get_attribute(name)
+          end
+
+        end
+
         # @return [Symbol,nil] The symbolic name of the table's hash key.
         def hash_key
           @keys.hash_key

data/lib/aws-record/record/client_configuration.rb

@@ -26,6 +26,8 @@ module Aws
       # in doubt, call this method to ensure your client is configured the way
       # you want it to be configured.
       #
+      # *Note*: {#dynamodb_client} is inherited from a parent model when
+      # +configure_client+ is explicitly specified in the parent.
       # @param [Hash] opts the options you wish to use to create the client.
       #  Note that if you include the option +:client+, all other options
       #  will be ignored. See the documentation for other options in the
@@ -33,15 +35,23 @@ module Aws
       # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
       #  own pre-configured client.
       def configure_client(opts = {})
-        @dynamodb_client = _build_client(opts)
+        if self.class != Module && Aws::Record.extends_record?(self) && opts.empty? &&
+          self.superclass.instance_variable_get('@dynamodb_client')
+            @dynamodb_client = self.superclass.instance_variable_get('@dynamodb_client')
+        else
+          @dynamodb_client = _build_client(opts)
+        end
       end
 
       # Gets the
-      # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html}
+      # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html Client}
       # instance that Transactions use. When called for the first time, if
       # {#configure_client} has not yet been called, will configure a new
       # client for you with default parameters.
       #
+      # *Note*: +dynamodb_client+ is inherited from a parent model when
+      # {configure_client} is explicitly specified in the parent.
+      #
       # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
       def dynamodb_client
         @dynamodb_client ||= configure_client

data/lib/aws-record/record/model_attributes.rb

@@ -32,6 +32,13 @@ module Aws
         attribute
       end
 
+      def register_superclass_attribute (name, attribute)
+        _new_attr_validation(name, attribute)
+        @attributes[name] = attribute.dup
+        @storage_attributes[attribute.database_name] = name
+        attribute
+      end
+
       def attribute_for(name)
         @attributes[name]
       end

data/lib/aws-record/record/secondary_indexes.rb

@@ -20,6 +20,17 @@ module Aws
         sub_class.instance_variable_set("@local_secondary_indexes", {})
         sub_class.instance_variable_set("@global_secondary_indexes", {})
         sub_class.extend(SecondaryIndexesClassMethods)
+        if Aws::Record.extends_record?(sub_class)
+          inherit_indexes(sub_class)
+        end
+      end
+
+      private
+      def self.inherit_indexes(klass)
+        superclass_lsi = klass.superclass.instance_variable_get("@local_secondary_indexes").dup
+        superclass_gsi = klass.superclass.instance_variable_get("@global_secondary_indexes").dup
+        klass.instance_variable_set("@local_secondary_indexes", superclass_lsi)
+        klass.instance_variable_set("@global_secondary_indexes", superclass_gsi)
       end
 
       module SecondaryIndexesClassMethods
@@ -28,6 +39,8 @@ module Aws
         # Secondary Indexes in the
         # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html Amazon DynamoDB Developer Guide}.
         #
+        # *Note*: {#local_secondary_indexes} is inherited from a parent model
+        # when +local_secondary_index+ is explicitly specified in the parent.
         # @param [Symbol] name index name for this local secondary index
         # @param [Hash] opts
         # @option opts [Symbol] :range_key the range key used by this local
@@ -46,6 +59,8 @@ module Aws
         # Global Secondary Indexes in the
         # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html Amazon DynamoDB Developer Guide}.
         #
+        # *Note*: {#global_secondary_indexes} is inherited from a parent model
+        # when +global_secondary_index+ is explicitly specified in the parent.
         # @param [Symbol] name index name for this global secondary index
         # @param [Hash] opts
         # @option opts [Symbol] :hash_key the hash key used by this global
@@ -60,12 +75,20 @@ module Aws
           global_secondary_indexes[name] = opts
         end
 
+        # Returns hash of local secondary index names to the index’s attributes.
+        #
+        # *Note*: +local_secondary_indexes+ is inherited from a parent model when {#local_secondary_index}
+        # is explicitly specified in the parent.
         # @return [Hash] hash of local secondary index names to the index's
         #   attributes.
         def local_secondary_indexes
           @local_secondary_indexes
         end
 
+        # Returns hash of global secondary index names to the index’s attributes.
+        #
+        # *Note*: +global_secondary_indexes+ is inherited from a parent model when {#global_secondary_index}
+        # is explicitly specified in the parent.
         # @return [Hash] hash of global secondary index names to the index's
         #   attributes.
         def global_secondary_indexes

data/lib/aws-record/record.rb

@@ -17,7 +17,19 @@ module Aws
   # decorate them with the Amazon DynamoDB integration methods provided by this
   # library. Methods you can use are shown below, in sub-modules organized by
   # functionality.
-  #
+  # === Inheritance Support
+  # Aws Record models can be extended using standard ruby inheritance. The child
+  # model must include +Aws::Record+ in their model and the following will
+  # be inherited:
+  # * {#set_table_name set_table_name}
+  # * {#initialize Attributes and keys}
+  # * Mutation Tracking:
+  #   * {#enable_mutation_tracking enable_mutation_tracking}
+  #   * {#disable_mutation_tracking disable_mutation_tracking}
+  # * {#local_secondary_indexes local_secondary_indexes}
+  # * {#global_secondary_indexes global_secondary_indexes}
+  # * {ClientConfiguration#configure_client configure_client}
+  # See example below to see the feature in action.
   # @example A class definition using +Aws::Record+
   #   class MyModel
   #     include Aws::Record
@@ -28,6 +40,21 @@ module Aws
   #     string_set_attr :tags
   #     map_attr        :metadata
   #   end
+  # @example Inheritance between models
+  #   class Animal
+  #     include Aws::Record
+  #     string_attr :name, hash_key: true
+  #     integer_attr :age
+  #   end
+  #
+  #   class Dog < Animal
+  #     include Aws::Record
+  #     boolean_attr :family_friendly
+  #   end
+  #
+  #   dog = Dog.find(name: 'Sunflower')
+  #   dog.age = 3
+  #   dog.family_friendly = true
   module Record
     # @!parse extend RecordClassMethods
     # @!parse include Attributes
@@ -57,6 +84,14 @@ module Aws
       sub_class.send(:include, DirtyTracking)
       sub_class.send(:include, Query)
       sub_class.send(:include, SecondaryIndexes)
+      if Aws::Record.extends_record?(sub_class)
+        inherit_track_mutations(sub_class)
+      end
+    end
+
+    # @api private
+    def self.extends_record?(klass)
+      klass.superclass.include?(Aws::Record)
     end
 
     private
@@ -64,6 +99,11 @@ module Aws
       self.class.dynamodb_client
     end
 
+    def self.inherit_track_mutations(klass)
+      superclass_track_mutations = klass.superclass.instance_variable_get("@track_mutations")
+      klass.instance_variable_set("@track_mutations", superclass_track_mutations)
+    end
+
     module RecordClassMethods
 
       # Returns the Amazon DynamoDB table name for this model class.
@@ -72,12 +112,14 @@ module Aws
       # also define a custom table name at the class level to be anything that
       # you want.
       #
+      # *Note*: +table_name+ is inherited from a parent model when {set_table_name}
+      # is explicitly specified in the parent.
       # @example
       #   class MyTable
       #     include Aws::Record
       #   end
       #
-      #   class MyTableTest
+      #   class MyOtherTable
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
@@ -85,29 +127,65 @@ module Aws
       #   MyTable.table_name      # => "MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
       def table_name
-        if @table_name
-          @table_name
-        else
-          @table_name = self.name.split("::").join("_")
+        @table_name ||= begin
+          if Aws::Record.extends_record?(self) &&
+              default_table_name(self.superclass) != self.superclass.table_name
+            self.superclass.instance_variable_get('@table_name')
+          else
+            default_table_name(self)
+          end
         end
       end
 
       # Allows you to set a custom Amazon DynamoDB table name for this model
       # class.
+      # === Inheritance Support
+      # +table_name+ is inherited from a parent model when it is explicitly specified
+      # in the parent.
       #
-      # @example
+      # The parent model will need to have +set_table_name+ defined in their model
+      # for the child model to inherit the +table_name+.
+      # If no +set_table_name+ is defined, the parent and child models will have separate
+      # table names based on their class name.
+      #
+      # If both parent and child models have defined +set_table_name+ in their model,
+      # the child model will override the +table_name+ with theirs.
+      # @example Setting custom table name for model class
       #   class MyTable
       #     include Aws::Record
       #     set_table_name "prod_MyTable"
       #   end
       #
-      #   class MyTableTest
+      #   class MyOtherTable
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
       #
       #   MyTable.table_name      # => "prod_MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
+      # @example Child model inherits table name from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     set_table_name "AnimalTable"
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #   end
+      #
+      #   Dog.table_name      # => "AnimalTable"
+      # @example Child model overrides table name from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     set_table_name "AnimalTable"
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #     set_table_name "DogTable"
+      #   end
+      #
+      #   Dog.table_name      # => "DogTable"
       def set_table_name(name)
         @table_name = name
       end
@@ -149,6 +227,9 @@ module Aws
       end
 
       # Turns off mutation tracking for all attributes in the model.
+      #
+      # *Note*: +disable_mutation_tracking+ is inherited from a parent model
+      # when it is explicitly specified in the parent.
       def disable_mutation_tracking
         @track_mutations = false
       end
@@ -158,6 +239,9 @@ module Aws
       # 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.
+      #
+      # *Note*: +enable_mutation_tracking+ is inherited from a parent model
+      # when it is explicitly specified in the parent.
       def enable_mutation_tracking
         @track_mutations = true
       end
@@ -177,6 +261,13 @@ module Aws
           raise Errors::InvalidModel.new("Table models must include a hash key")
         end
       end
+
+      private
+      def default_table_name(klass)
+        return unless klass.name
+        klass.name.split("::").join("_")
+      end
+
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-28 00:00:00.000000000 Z
+date: 2022-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.7
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: AWS Record library for Amazon DynamoDB