aws-record 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aaa5337431b2b2f59b35245afd1fb9eb4cacb5226f9cc60a2fefeed5bde7619
-  data.tar.gz: 8e8a225d9abfb3ec8ca8ee30606df05016166bbb10e0affc4d81fbfbcaaa21f4
+  metadata.gz: 6316b0ad6349fdea29d10e1325b6044b54eb3f2696a9bd1692cc30881e5e2e02
+  data.tar.gz: 57c1d3c37435e3bc79eac488738c08f8ac6536bfbd5f493ac221f248bdf3e8c8
 SHA512:
-  metadata.gz: f3ca0395934b8b5f464e7208c8b9b55c104475a045e6e93c01d9a8dfbcbbcab5bed6e4d3563ff963d43a93cce79e2918bfba032e4dab83d42168603289aa2bee
-  data.tar.gz: 5ed32da4f64d414076c16265ae5200beeb2a02225fb03cc9626626df9bdc1e07a48918231576236e59a22edff0e940fb48be582f7a3fb7162353bbeb6cc9a4fc
+  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.

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.8.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-12 00:00:00.000000000 Z
+date: 2022-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb