aws-record 2.7.0 → 2.10.1

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

@@ -1,15 +1,4 @@
-# Copyright 2015-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You may not
-# use this file except in compliance with the License. A copy of the License is
-# located at
-#
-#     http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
-# or implied. See the License for the specific language governing permissions
-# and limitations under the License.
+# frozen_string_literal: true
 
 module Aws
   module Record

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

@@ -1,15 +1,4 @@
-# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You may not
-# use this file except in compliance with the License. A copy of the License is
-# located at
-#
-#     http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
-# or implied. See the License for the specific language governing permissions
-# and limitations under the License.
+# frozen_string_literal: true
 
 module Aws
   module Record

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Aws
   module Record
     module Transactions
@@ -26,15 +28,26 @@ module Aws
         #   ) # => results.responses contains nil or marshalled items
         #   results.responses.map { |r| r.class } # [TableOne, TableTwo, TableTwo]
         #
-        # Provides a way to run a transactional find across multiple DynamoDB
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_get_items-instance_method
+        # Aws::DynamoDB::Client#transact_get_item} for aws-record models.
+        #
+        # This method runs a transactional find across multiple DynamoDB
         # items, including transactions which get items across multiple actual
-        # or virtual tables.
+        # or virtual tables. This call can contain up to 100 item keys.
+        #
+        # DynamoDB will reject the request if any of the following is true:
+        # * A conflicting operation is in the process of updating an item to be read.
+        # * There is insufficient provisioned capacity for the transaction to be completed.
+        # * There is a user error, such as an invalid data format.
+        # * The aggregate size of the items in the transaction cannot exceed 4 MB.
         #
         # @param [Hash] opts Options to pass through to
         #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_get_items-instance_method Aws::DynamoDB::Client#transact_get_items},
-        #   with the exception of the :transact_items array, which uses the
-        #   +#tfind_opts+ operation on your model class to provide extra
-        #   metadata used to marshal your items after retrieval.
+        #   with the exception of the +:transact_items+ array, which uses the
+        #   {ItemOperations.ItemOperationsClassMethods.tfind_opts #tfind_opts} operation
+        #   on your model class to provide extra metadata used to marshal your items
+        #   after retrieval.
         # @option opts [Array] :transact_items A set of +#tfind_opts+ results,
         #   such as those created by the usage example.
         # @option opts [Aws::DynamoDB::Client] :client Optionally, you can pass
@@ -137,7 +150,11 @@ module Aws
         #     ]
         #   )
         #
-        # Provides a way to pass in aws-record items into transactional writes,
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_write_items-instance_method
+        # Aws::DynamoDB::Client#transact_write_items} for aws-record models.
+        #
+        # This method passes in aws-record items into transactional writes,
         # as well as adding the ability to run 'save' commands in a transaction
         # while allowing aws-record to determine if a :put or :update operation
         # is most appropriate. +#transact_write+ supports 5 different transact
@@ -145,7 +162,7 @@ module Aws
         # - save: Behaves much like the +#save+ operation on the item itself.
         #   If the keys are dirty, and thus it appears to be a new item, will
         #   create a :put operation with a conditional check on the item's
-        #   existance. Note that you cannot bring your own conditional
+        #   existence. Note that you cannot bring your own conditional
         #   expression in this case. If you wish to force put or add your
         #   own conditional checks, use the :put operation.
         # - put: Does a force put for the given item key and model.
@@ -153,6 +170,21 @@ module Aws
         # - delete: Deletes the given item.
         # - check: Takes the result of +#transact_check_expression+,
         #   performing the specified check as a part of the transaction.
+        #   See {ItemOperations.ItemOperationsClassMethods.transact_check_expression #transact_check_expression}
+        #   for more information.
+        #
+        # This call contain up to 100 action requests.
+        #
+        # DynamoDB will reject the request if any of the following is true:
+        # * A condition in one of the condition expressions is not met.
+        # * An ongoing operation is in the process of updating the same item.
+        # * There is insufficient provisioned capacity for the transaction to
+        #   be completed.
+        # * An item size becomes too large (bigger than 400 KB), a local secondary
+        #   index (LSI) becomes too large, or a similar validation error occurs
+        #   because of changes made by the transaction.
+        # * The aggregate size of the items in the transaction exceeds 4 MB.
+        # * There is a user error, such as an invalid data format.
         #
         # @param [Hash] opts Options to pass through to
         #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_write_items-instance_method Aws::DynamoDB::Client#transact_write_items}

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

@@ -1,18 +1,7 @@
-# Copyright 2015-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You may not
-# use this file except in compliance with the License. A copy of the License is
-# located at
-#
-#     http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
-# or implied. See the License for the specific language governing permissions
-# and limitations under the License.
+# frozen_string_literal: true
 
 module Aws
   module Record
-    VERSION = '2.7.0'
+    VERSION = File.read(File.expand_path('../../../../VERSION', __FILE__)).strip
   end
 end

data/lib/aws-record/record.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You may not
-# use this file except in compliance with the License. A copy of the License is
-# located at
-#
-#     http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
-# or implied. See the License for the specific language governing permissions
-# and limitations under the License.
+# frozen_string_literal: true
 
 module Aws
 
@@ -17,7 +6,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 +29,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 +73,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 +88,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 +101,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 +116,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 +216,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 +228,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 +250,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

data/lib/aws-record.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You may not
-# use this file except in compliance with the License. A copy of the License is
-# located at
-#
-#     http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is distributed on
-# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
-# or implied. See the License for the specific language governing permissions
-# and limitations under the License.
+# frozen_string_literal: true
 
 require 'aws-sdk-dynamodb'
 require_relative 'aws-record/record/client_configuration'
@@ -30,6 +19,7 @@ require_relative 'aws-record/record/table_migration'
 require_relative 'aws-record/record/version'
 require_relative 'aws-record/record/transactions'
 require_relative 'aws-record/record/buildable_search'
+require_relative 'aws-record/record/batch_read'
 require_relative 'aws-record/record/batch_write'
 require_relative 'aws-record/record/batch'
 require_relative 'aws-record/record/marshalers/string_marshaler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.10.1
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-28 00:00:00.000000000 Z
+date: 2023-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -32,11 +32,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- VERSION
 - lib/aws-record.rb
 - lib/aws-record/record.rb
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
 - lib/aws-record/record/batch.rb
+- lib/aws-record/record/batch_read.rb
 - lib/aws-record/record/batch_write.rb
 - lib/aws-record/record/buildable_search.rb
 - lib/aws-record/record/client_configuration.rb
@@ -65,7 +69,7 @@ files:
 - lib/aws-record/record/table_migration.rb
 - lib/aws-record/record/transactions.rb
 - lib/aws-record/record/version.rb
-homepage: http://github.com/aws/aws-sdk-ruby-record
+homepage: https://github.com/aws/aws-sdk-ruby-record
 licenses:
 - Apache 2.0
 metadata: {}
@@ -84,7 +88,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