aws-record 2.2.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76f3f70bc226f5e34e377328a8829db296bffa304238da8d7542a947ba0b7a9e
-  data.tar.gz: f22f14e087edf96717fbaffd03bc7b3917001fb5238597994143b50bc5e16894
+  metadata.gz: 309ae7c37a70b41c9bb7695bd0c79a5faa83195c764986f28d43becc61f82f09
+  data.tar.gz: d13944acd83e60191102e72078cd399190dfc0632a670a791134c33382578260
 SHA512:
-  metadata.gz: 745aff26cc027c53552b456066b56900f1489c1aa4433b8e539d1ac6f093d0cbaa62dec5054b433d2f8f2f42220471cca55dcdb6fa0d6ae1d23f542318ccd296
-  data.tar.gz: 2e20c004f7ca252dfdff66eb4005137c74da60a964ce4862bb2390fceaf6ce2fe0f1c63bcdc00a1671f13c69dc6165b0488afc1ba4779b524ba1740c1d7f2591
+  metadata.gz: c4ad5ee650e8d785eee3fac8b5f33f5e2db82ea3fd903bbde374e5d85920ec92c85c724fe55ed913befcb5ad5b1c27e9d38ebc3c41a7ae4c3eefe9cba45ea690
+  data.tar.gz: 8f014faf8d060af4db13acde3cdbc67e8a34a534c612c8a7b739911d1ea568743fb899ff88b11474e46417af7ad25761dd3a7cabda850c96c79297ef4b79981c

data/lib/aws-record.rb

@@ -27,6 +27,8 @@ require_relative 'aws-record/record/secondary_indexes'
 require_relative 'aws-record/record/table_config'
 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/marshalers/string_marshaler'
 require_relative 'aws-record/record/marshalers/boolean_marshaler'
 require_relative 'aws-record/record/marshalers/integer_marshaler'

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

@@ -48,12 +48,14 @@ module Aws
       #   item is nil or not set at persistence time.
       def initialize(name, options = {})
         @name = name
-        @database_name = options[:database_attribute_name] || name.to_s
+        @database_name = (options[:database_attribute_name]  || name).to_s
         @dynamodb_type = options[:dynamodb_type]
         @marshaler = options[:marshaler] || DefaultMarshaler
         @persist_nil = options[:persist_nil]
         dv = options[:default_value]
-        @default_value_or_lambda = type_cast(dv) unless dv.nil?
+        unless dv.nil?
+          @default_value_or_lambda = _is_lambda?(dv) ? dv : type_cast(dv)
+        end
       end
 
       # Attempts to type cast a raw value into the attribute's type. This call
@@ -92,8 +94,8 @@ module Aws
 
       # @api private
       def default_value
-        if @default_value_or_lambda.respond_to?(:call)
-          @default_value_or_lambda.call
+        if _is_lambda?(@default_value_or_lambda)
+          type_cast(@default_value_or_lambda.call)
         else
           _deep_copy(@default_value_or_lambda)
         end
@@ -104,6 +106,10 @@ module Aws
         Marshal.load(Marshal.dump(obj))
       end
 
+      def _is_lambda?(obj)
+        obj.respond_to?(:call)
+      end
+
     end
 
     # This is an identity marshaler, which performs no changes for type casting

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

@@ -0,0 +1,276 @@
+module Aws
+  module Record
+    class BuildableSearch
+      SUPPORTED_OPERATIONS = [:query, :scan]
+
+      # This should never be called directly, rather it is called by the
+      # #build_query or #build_scan methods of your aws-record model class.
+      def initialize(opts)
+        operation = opts[:operation]
+        model = opts[:model]
+        if SUPPORTED_OPERATIONS.include?(operation)
+          @operation = operation
+        else
+          raise ArgumentError.new("Unsupported operation: #{operation}")
+        end
+        @model = model
+        @params = {}
+        @next_name = "BUILDERA"
+        @next_value = "buildera"
+      end
+
+      # If you are querying or scanning on an index, you can specify it with
+      # this builder method. Provide the symbol of your index as defined on your
+      # model class.
+      def on_index(index)
+        @params[:index_name] = index
+        self
+      end
+
+      # If true, will perform your query or scan as a consistent read. If false,
+      # the query or scan is eventually consistent.
+      def consistent_read(b)
+        @params[:consistent_read] = b
+        self
+      end
+
+      # For the scan operation, you can split your scan into multiple segments
+      # to be scanned in parallel. If you wish to do this, you can use this
+      # builder method to provide the :total_segments of your parallel scan and
+      # the :segment number of this scan.
+      def parallel_scan(opts)
+        unless @operation == :scan
+          raise ArgumentError.new("parallel_scan is only supported for scans")
+        end
+        unless opts[:total_segments] && opts[:segment]
+          raise ArgumentError.new("Must specify :total_segments and :segment in a parallel scan.")
+        end
+        @params[:total_segments] = opts[:total_segments]
+        @params[:segment] = opts[:segment]
+        self
+      end
+
+      # For a query operation, you can use this to set if you query is in
+      # ascending or descending order on your range key. By default, a query is
+      # run in ascending order.
+      def scan_ascending(b)
+        unless @operation == :query
+          raise ArgumentError.new("scan_ascending is only supported for queries.")
+        end
+        @params[:scan_index_forward] = b
+        self
+      end
+
+      # If you have an exclusive start key for your query or scan, you can
+      # provide it with this builder method. You should not use this if you are
+      # querying or scanning without a set starting point, as the
+      # {Aws::Record::ItemCollection} class handles pagination automatically
+      # for you.
+      def exclusive_start_key(key)
+        @params[:exclusive_start_key] = key
+        self
+      end
+
+      # Provide a key condition expression for your query using a substitution
+      # expression.
+      #
+      # @example Building a simple query with a key expression:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #   end
+      #
+      #   q = ExampleTable.build_query.key_expr(
+      #         ":uuid = ? AND :id > ?", "smpl-uuid", 100
+      #       ).complete!
+      #   q.to_a # You can use this like any other query result in aws-record
+      def key_expr(statement_str, *subs)
+        unless @operation == :query
+          raise ArgumentError.new("key_expr is only supported for queries.")
+        end
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        values = @params[:expression_attribute_values]
+        if values.nil?
+          @params[:expression_attribute_values] = {}
+          values = @params[:expression_attribute_values]
+        end
+        _key_pass(statement_str, names)
+        _apply_values(statement_str, subs, values)
+        @params[:key_condition_expression] = statement_str
+        self
+      end
+
+      # Provide a filter expression for your query or scan using a substitution
+      # expression.
+      #
+      # @example Building a simple scan:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #   end
+      #
+      #   scan = ExampleTable.build_scan.filter_expr(
+      #     "contains(:body, ?)",
+      #     "bacon"
+      #   ).complete!
+      # 
+      def filter_expr(statement_str, *subs)
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        values = @params[:expression_attribute_values]
+        if values.nil?
+          @params[:expression_attribute_values] = {}
+          values = @params[:expression_attribute_values]
+        end
+        _key_pass(statement_str, names)
+        _apply_values(statement_str, subs, values)
+        @params[:filter_expression] = statement_str
+        self
+      end
+
+      # Allows you to define a projection expression for the values returned by
+      # a query or scan. See
+      # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html the Amazon DynamoDB Developer Guide}
+      # for more details on projection expressions. You can use the symbols from
+      # your aws-record model class in a projection expression. Keys are always
+      # retrieved.
+      #
+      # @example Scan with a projection expression:
+      #   # Example model class
+      #   class ExampleTable
+      #     include Aws::Record
+      #     string_attr  :uuid, hash_key: true
+      #     integer_attr :id,   range_key: true
+      #     string_attr  :body
+      #     map_attr     :metadata
+      #   end
+      #
+      #   scan = ExampleTable.build_scan.projection_expr(
+      #     ":body"
+      #   ).complete!
+      def projection_expr(statement_str)
+        names = @params[:expression_attribute_names]
+        if names.nil?
+          @params[:expression_attribute_names] = {}
+          names = @params[:expression_attribute_names]
+        end
+        _key_pass(statement_str, names)
+        @params[:projection_expression] = statement_str
+        self
+      end
+
+      # Allows you to set a page size limit on each query or scan request.
+      def limit(size)
+        @params[:limit] = size
+        self
+      end
+
+      # Allows you to define a callback that will determine the model class
+      # to be used for each item, allowing queries to return an ItemCollection
+      # with mixed models.  The provided block must return the model class based on
+      # any logic on the raw item attributes or `nil` if no model applies and
+      # the item should be skipped.  Note: The block only has access to raw item
+      # data so attributes must be accessed using their names as defined in the
+      # table, not as the symbols defined in the model class(s).
+      #
+      # @example Scan with heterogeneous results:
+      #   # Example model classes
+      #   class Model_A
+      #     include Aws::Record
+      #     set_table_name(TABLE_NAME)
+      #
+      #     string_attr :uuid, hash_key: true
+      #     string_attr :class_name, range_key: true
+      #
+      #     string_attr :attr_a
+      #   end
+      #
+      #   class Model_B
+      #     include Aws::Record
+      #     set_table_name(TABLE_NAME)
+      #
+      #     string_attr :uuid, hash_key: true
+      #     string_attr :class_name, range_key: true
+      #
+      #     string_attr :attr_b
+      #   end
+      #
+      #   # use multi_model_filter to create a query on TABLE_NAME
+      #   items = Model_A.build_scan.multi_model_filter do |raw_item_attributes|
+      #     case raw_item_attributes['class_name']
+      #     when "A" then Model_A
+      #     when "B" then Model_B
+      #     else
+      #       nil
+      #     end
+      #   end.complete!
+      def multi_model_filter(proc = nil, &block)
+        @params[:model_filter] = proc || block
+        self
+      end
+
+      # You must call this method at the end of any query or scan you build.
+      #
+      # @return [Aws::Record::ItemCollection] The item collection lazy
+      #   enumerable.
+      def complete!
+        @model.send(@operation, @params)
+      end
+
+      private
+      def _key_pass(statement, names)
+        statement.gsub!(/:(\w+)/) do |match|
+          key = match.gsub!(':','').to_sym 
+          key_name = @model.attributes.storage_name_for(key)
+          if key_name
+            sub_name = _next_name
+            raise "Substitution collision!" if names[sub_name]
+            names[sub_name] = key_name
+            sub_name
+          else
+            raise "No such key #{key}"
+          end
+        end
+      end
+
+      def _apply_values(statement, subs, values)
+        count = 0
+        statement.gsub!(/[?]/) do |match|
+          sub_value = _next_value
+          raise "Substitution collision!" if values[sub_value]
+          values[sub_value] = subs[count]
+          count += 1
+          sub_value
+        end
+        unless count == subs.size
+          raise "Expected #{count} values in the substitution set, but found #{subs.size}"
+        end
+      end
+
+      def _next_name
+        ret = "#" + @next_name
+        @next_name.next!
+        ret
+      end
+
+      def _next_value
+        ret = ":" + @next_value
+        @next_value.next!
+        ret
+      end
+    end
+  end
+end

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

@@ -54,6 +54,14 @@ module Aws
       class TableDoesNotExist < RuntimeError; end
 
       class MissingRequiredConfiguration < RuntimeError; end
+
+      # Raised when you attempt to combine your own condition expression with
+      # the auto-generated condition expression from a "safe put" from saving
+      # a new item in a transactional write operation. The path forward until
+      # this case is supported is to use a plain "put" call, and to include
+      # the key existance check yourself in your condition expression if you
+      # wish to do so.
+      class TransactionalSaveConditionCollision < RuntimeError; end
     end
   end
 end

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

@@ -19,6 +19,7 @@ module Aws
       def initialize(search_method, search_params, model, client)
         @search_method = search_method
         @search_params = search_params
+        @model_filter = @search_params.delete(:model_filter)
         @model = model
         @client = client
       end
@@ -91,9 +92,11 @@ module Aws
       def _build_items_from_response(items, model)
         ret = []
         items.each do |item|
-          record = model.new
+          model_class = @model_filter ? @model_filter.call(item) : model
+          next unless model_class
+          record = model_class.new
           data = record.instance_variable_get("@data")
-          model.attributes.attributes.each do |name, attr|
+          model_class.attributes.attributes.each do |name, attr|
             data.set_attribute(name, attr.extract(item))
           end
           data.clean!

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

@@ -122,9 +122,9 @@ module Aws
 
       def populate_default_values
         @model_attributes.attributes.each do |name, attribute|
-          unless attribute.default_value.nil?
+          unless (default_value = attribute.default_value).nil?
             if @data[name].nil? && @data[name].nil?
-              @data[name] = attribute.default_value
+              @data[name] = default_value
             end
           end
         end

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

@@ -82,8 +82,7 @@ module Aws
       end
 
 
-      # Deletes the item instance that matches the key values of this item
-      # instance in Amazon DynamoDB.
+      # Assigns the attributes provided onto the model.
       #
       # @example Usage Example
       #   class MyModel
@@ -329,6 +328,112 @@ module Aws
 
       module ItemOperationsClassMethods
 
+        # @example Usage Example
+        #   check_exp = Model.transact_check_expression(
+        #     key: { uuid: "foo" },
+        #     condition_expression: "size(#T) <= :v",
+        #     expression_attribute_names: {
+        #       "#T" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":v" => 1024
+        #     }
+        #   )
+        # 
+        # Allows you to build a "check" expression for use in transactional
+        # write operations.
+        #
+        # @param [Hash] opts Options matching the :condition_check contents in
+        #   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}
+        #   API, with the exception that keys will be marshalled for you, and
+        #   the table name will be provided for you by the operation.
+        # @return [Hash] Options suitable to be used as a check expression when
+        #   calling the +#transact_write+ operation.
+        def transact_check_expression(opts)
+          # need to transform the key, and add the table name
+          opts = opts.dup
+          key = opts.delete(:key)
+          check_key = {}
+          @keys.keys.each_value do |attr_sym|
+            unless key[attr_sym]
+              raise Errors::KeyMissing.new(
+                "Missing required key #{attr_sym} in #{key}"
+              )
+            end
+            attr_name = attributes.storage_name_for(attr_sym)
+            check_key[attr_name] = attributes.attribute_for(attr_sym).
+              serialize(key[attr_sym])
+          end
+          opts[:key] = check_key
+          opts[:table_name] = table_name
+          opts
+        end
+
+        def tfind_opts(opts)
+          opts = opts.dup
+          key = opts.delete(:key)
+          request_key = {}
+          @keys.keys.each_value do |attr_sym|
+            unless key[attr_sym]
+              raise Errors::KeyMissing.new(
+                "Missing required key #{attr_sym} in #{key}"
+              )
+            end
+            attr_name = attributes.storage_name_for(attr_sym)
+            request_key[attr_name] = attributes.attribute_for(attr_sym).
+              serialize(key[attr_sym])
+          end
+          # this is a :get item used by #transact_get_items, with the exception
+          # of :model_class which needs to be removed before passing along
+          opts[:key] = request_key
+          opts[:table_name] = table_name
+          {
+            model_class: self,
+            get: opts
+          }
+        end
+
+        # @example Usage Example
+        #   class Table
+        #     include Aws::Record
+        #     string_attr :hk, hash_key: true
+        #     string_attr :rk, range_key: true
+        #   end
+        #   
+        #   results = Table.transact_find(
+        #     transact_items: [
+        #       {key: { hk: "hk1", rk: "rk1"}},
+        #       {key: { hk: "hk2", rk: "rk2"}}
+        #     ]
+        #   ) # => results.responses contains nil or instances of Table
+        #
+        # Provides a way to run a transactional find across multiple DynamoDB
+        # items, including transactions which get items across multiple actual
+        # or virtual tables.
+        #
+        # @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.
+        # @option opts [Array] :transact_items A set of options describing
+        #   instances of the model class to return.
+        # @return [OpenStruct] Structured like the client API response from
+        #   +#transact_get_items+, except that the +responses+ member contains
+        #   +Aws::Record+ items marshaled into the model class used to call
+        #   this method. See the usage example.
+        def transact_find(opts)
+          opts = opts.dup
+          transact_items = opts.delete(:transact_items)
+          global_transact_items = transact_items.map do |topts|
+            tfind_opts(topts)
+          end
+          opts[:transact_items] = global_transact_items
+          opts[:client] = dynamodb_client
+          Transactions.transact_find(opts)
+        end
+
         # @example Usage Example
         #   class MyModel
         #     include Aws::Record

data/lib/aws-record/record/marshalers/numeric_set_marshaler.rb

@@ -58,7 +58,7 @@ module Aws
             if item.is_a?(Numeric)
               item
             else
-              BigDecimal.new(item.to_s)
+              BigDecimal(item.to_s)
             end
           end
         end

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

@@ -102,6 +102,54 @@ module Aws
           scan_opts = opts.merge(table_name: table_name)
           ItemCollection.new(:scan, scan_opts, self, dynamodb_client)
         end
+
+        # This method allows you to build a query using the {Aws::Record::BuildableSearch} DSL.
+        #
+        # @example Building a simple query:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   q = ExampleTable.build_query.key_expr(
+        #         ":uuid = ? AND :id > ?", "smpl-uuid", 100
+        #       ).scan_ascending(false).complete!
+        #   q.to_a # You can use this like any other query result in aws-record
+        def build_query
+          BuildableSearch.new(
+            operation: :query,
+            model: self
+          )
+        end
+
+        # This method allows you to build a scan using the {Aws::Record::BuildableSearch} DSL.
+        #
+        # @example Building a simple scan:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   segment_2_scan = ExampleTable.build_scan.filter_expr(
+        #     "contains(:body, ?)",
+        #     "bacon"
+        #   ).scan_ascending(false).parallel_scan(
+        #     total_segments: 5,
+        #     segment: 2
+        #   ).complete!
+        #   segment_2_scan.to_a # You can use this like any other query result in aws-record
+        def build_scan
+          BuildableSearch.new(
+            operation: :scan,
+            model: self
+          )
+        end
       end
 
     end

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

@@ -56,15 +56,24 @@ module Aws
       # @param [Hash] opts options to pass on to the client call to
       #  +#create_table+. See the documentation above in the AWS SDK for Ruby
       #  V2.
-      # @option opts [Hash] :provisioned_throughput This is a required argument,
-      #  in which you must specify the +:read_capacity_units+ and
+      # @option opts [Hash] :billing_mode Accepts values 'PAY_PER_REQUEST' or
+      #  'PROVISIONED'. If :provisioned_throughput option is specified, this
+      #  option is not required, as 'PROVISIONED' is assumed. If
+      #  :provisioned_throughput is not specified, this option is required
+      #  and must be set to 'PAY_PER_REQUEST'.
+      # @option opts [Hash] :provisioned_throughput Unless :billing_mode is
+      #  set to 'PAY_PER_REQUEST', this is a required argument, in which
+      #  you must specify the +:read_capacity_units+ and
       #  +:write_capacity_units+ of your new table.
       # @option opts [Hash] :global_secondary_index_throughput This argument is
-      #  required if you define any global secondary indexes. It should map your
+      #  required if you define any global secondary indexes, unless
+      #  :billing_mode is set to 'PAY_PER_REQUEST'. It should map your
       #  global secondary index names to their provisioned throughput, similar
       #  to how you define the provisioned throughput for the table in general.
       def create!(opts)
         gsit = opts.delete(:global_secondary_index_throughput)
+        _validate_billing(opts)
+
         create_opts = opts.merge({
           table_name: @model.table_name,
           attribute_definitions: _attribute_definitions,
@@ -75,14 +84,19 @@ module Aws
           _append_to_attribute_definitions(lsis, create_opts)
         end
         if gsis = @model.global_secondary_indexes_for_migration
-          unless gsit
+          unless gsit || opts[:billing_mode] == 'PAY_PER_REQUEST'
             raise ArgumentError.new(
-              "If you define global secondary indexes, you must also define"\
-                " :global_secondary_index_throughput on table creation."
+              'If you define global secondary indexes, you must also define'\
+                ' :global_secondary_index_throughput on table creation,'\
+                " unless :billing_mode is set to 'PAY_PER_REQUEST'."
             )
           end
-          gsis_with_throughput = _add_throughout_to_gsis(gsis, gsit)
-          create_opts[:global_secondary_indexes] = gsis_with_throughput
+          gsis_opts = if opts[:billing_mode] == 'PAY_PER_REQUEST'
+                        gsis
+                      else
+                        _add_throughput_to_gsis(gsis, gsit)
+                      end
+          create_opts[:global_secondary_indexes] = gsis_opts
           _append_to_attribute_definitions(gsis, create_opts)
         end
         @client.create_table(create_opts)
@@ -142,6 +156,33 @@ module Aws
         end
       end
 
+      def _validate_billing(opts)
+        valid_modes = %w[PAY_PER_REQUEST PROVISIONED]
+        if opts.key?(:billing_mode)
+          unless valid_modes.include?(opts[:billing_mode])
+            raise ArgumentError.new(
+              ":billing_mode option must be one of #{valid_modes.join(', ')}"\
+                " current value is: #{opts[:billing_mode]}"
+            )
+          end
+        end
+        if opts.key?(:provisioned_throughput)
+          if opts[:billing_mode] == 'PAY_PER_REQUEST'
+            raise ArgumentError.new(
+              'when :provisioned_throughput option is specified, :billing_mode'\
+                " must either be unspecified or have a value of 'PROVISIONED'"
+            )
+          end
+        else
+          if opts[:billing_mode] != 'PAY_PER_REQUEST'
+            raise ArgumentError.new(
+              'when :provisioned_throughput option is not specified,'\
+                " :billing_mode must be set to 'PAY_PER_REQUEST'"
+            )
+          end
+        end
+      end
+
       def _attribute_definitions
         _keys.map do |type, attr|
           {
@@ -173,7 +214,7 @@ module Aws
         create_opts[:attribute_definitions] = attr_def
       end
 
-      def _add_throughout_to_gsis(global_secondary_indexes, gsi_throughput)
+      def _add_throughput_to_gsis(global_secondary_indexes, gsi_throughput)
         missing_throughput = []
         ret = global_secondary_indexes.map do |params|
           name = params[:index_name]

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

@@ -0,0 +1,332 @@
+module Aws
+  module Record
+    module Transactions
+      class << self
+
+        # @example Usage Example
+        #   class TableOne
+        #     include Aws::Record
+        #     string_attr :uuid, hash_key: true
+        #   end
+        #   
+        #   class TableTwo
+        #     include Aws::Record
+        #     string_attr :hk, hash_key: true
+        #     string_attr :rk, range_key: true
+        #   end
+        #   
+        #   results = Aws::Record::Transactions.transact_find(
+        #     transact_items: [
+        #       TableOne.tfind_opts(key: { uuid: "uuid1234" }),
+        #       TableTwo.tfind_opts(key: { hk: "hk1", rk: "rk1"}),
+        #       TableTwo.tfind_opts(key: { hk: "hk2", rk: "rk2"})
+        #     ]
+        #   ) # => 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
+        # items, including transactions which get items across multiple actual
+        # or virtual tables.
+        #
+        # @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.
+        # @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
+        #   in your own client to use for the transaction calls.
+        # @return [OpenStruct] Structured like the client API response from
+        #   +#transact_get_items+, except that the +responses+ member contains
+        #   +Aws::Record+ items marshaled into the classes used to call
+        #   +#tfind_opts+ in each positional member. See the usage example.
+        def transact_find(opts)
+          opts = opts.dup
+          client = opts.delete(:client) || dynamodb_client
+          transact_items = opts.delete(:transact_items) # add nil check?
+          model_classes = []
+          client_transact_items = transact_items.map do |tfind_opts|
+            model_class = tfind_opts.delete(:model_class)
+            model_classes << model_class
+            tfind_opts
+          end
+          request_opts = opts
+          request_opts[:transact_items] = client_transact_items
+          client_resp = client.transact_get_items(
+            request_opts
+          )
+          responses = client_resp.responses
+          index = -1
+          ret = OpenStruct.new
+          ret.consumed_capacity = client_resp.consumed_capacity
+          ret.missing_items = []
+          ret.responses = client_resp.responses.map do |item|
+            index += 1
+            if item.nil? || item.item.nil?
+              missing_data = {
+                model_class: model_classes[index],
+                key: transact_items[index][:get][:key]
+              }
+              ret.missing_items << missing_data
+              nil
+            else
+              # need to translate the item keys
+              raw_item = item.item
+              model_class = model_classes[index]
+              new_item_opts = {}
+              raw_item.each do |db_name, value|
+                name = model_class.attributes.db_to_attribute_name(db_name)
+                new_item_opts[name] = value
+              end
+              item = model_class.new(new_item_opts)
+              item.clean!
+              item
+            end
+          end
+          ret
+        end
+
+        # @example Usage Example
+        #   class TableOne
+        #     include Aws::Record
+        #     string_attr :uuid, hash_key: true
+        #     string_attr :body
+        #   end
+        #   
+        #   class TableTwo
+        #     include Aws::Record
+        #     string_attr :hk, hash_key: true
+        #     string_attr :rk, range_key: true
+        #     string_attr :body
+        #   end
+        #   
+        #   check_exp = TableOne.transact_check_expression(
+        #     key: { uuid: "foo" },
+        #     condition_expression: "size(#T) <= :v",
+        #     expression_attribute_names: {
+        #       "#T" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":v" => 1024
+        #     }
+        #   )
+        #   new_item = TableTwo.new(hk: "hk1", rk: "rk1", body: "Hello!")
+        #   update_item_1 = TableOne.find(uuid: "bar")
+        #   update_item_1.body = "Updated the body!"
+        #   put_item = TableOne.new(uuid: "foobar", body: "Content!")
+        #   update_item_2 = TableTwo.find(hk: "hk2", rk: "rk2")
+        #   update_item_2.body = "Update!"
+        #   delete_item = TableOne.find(uuid: "to_be_deleted")
+        #   
+        #   Aws::Record::Transactions.transact_write(
+        #     transact_items: [
+        #       { check: check_exp },
+        #       { save: new_item },
+        #       { save: update_item_1 },
+        #       {
+        #          put: put_item,
+        #          condition_expression: "attribute_not_exists(#H)",
+        #          expression_attribute_names: { "#H" => "uuid" },
+        #          return_values_on_condition_check_failure: "ALL_OLD"
+        #       },
+        #       { update: update_item_2 },
+        #       { delete: delete_item }
+        #     ]
+        #   )
+        #
+        # Provides a way to pass 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
+        # item modes:
+        # - 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
+        #   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.
+        # - update: Does an upsert for the given item.
+        # - delete: Deletes the given item.
+        # - check: Takes the result of +#transact_check_expression+,
+        #   performing the specified check as a part of the transaction.
+        #
+        # @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}
+        #   with the exception of :transact_items array, which is transformed
+        #   to use your item to populate the :key, :table_name, :item, and/or
+        #   :update_expression parameters as appropriate. See the usage example
+        #   for a comprehensive set of combinations.
+        # @option opts [Array] :transact_items An array of hashes, accepting
+        #   +:save+, +:put+, +:delete+, +:update+, and +:check+ as specified.
+        # @option opts [Aws::DynamoDB::Client] :client Optionally, you can
+        #   specify a client to use for this transaction call. If not
+        #   specified, the configured client for +Aws::Record::Transactions+
+        #   is used.
+        def transact_write(opts)
+          opts = opts.dup
+          client = opts.delete(:client) || dynamodb_client
+          dirty_items = []
+          delete_items = []
+          # fetch abstraction records
+          transact_items = _transform_transact_write_items(
+            opts.delete(:transact_items),
+            dirty_items,
+            delete_items
+          )
+          opts[:transact_items] = transact_items
+          resp = client.transact_write_items(opts)
+          # mark all items clean/destroyed as needed if we didn't raise an exception
+          dirty_items.each { |i| i.clean! }
+          delete_items.each { |i| i.instance_variable_get("@data").destroyed = true }
+          resp
+        end
+
+        # Configures the Amazon DynamoDB client used by global transaction
+        # operations.
+        #
+        # Please note that this method is also called internally when you first
+        # attempt to perform an operation against the remote end, if you have
+        # not already configured a client. As such, please read and understand
+        # the documentation in the AWS SDK for Ruby V3 around
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/#Configuration configuration}
+        # to ensure you understand how default configuration behavior works.
+        # When in doubt, call this method to ensure your client is configured
+        # the way you want it to be configured.
+        #
+        # @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
+        #  {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#initialize-instance_method AWS SDK for Ruby V3}.
+        # @option opts [Aws::DynamoDB::Client] :client allows you to pass in
+        #  your own pre-configured client.
+        def configure_client(opts = {})
+          provided_client = opts.delete(:client)
+          opts[:user_agent_suffix] = _user_agent(
+            opts.delete(:user_agent_suffix)
+          )
+          client = provided_client || Aws::DynamoDB::Client.new(opts)
+          @@dynamodb_client = client
+        end
+
+        # Gets the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html}
+        # 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.
+      #
+      # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
+        def dynamodb_client
+          @@dynamodb_client ||= configure_client
+        end
+
+        private
+        def _transform_transact_write_items(transact_items, dirty_items, delete_items)
+          transact_items.map do |item|
+            # this code will assume users only provided one operation, and
+            # will fail down the line if that assumption is wrong
+            if save_record = item.delete(:save)
+              dirty_items << save_record
+              _transform_save_record(save_record, item)
+            elsif put_record = item.delete(:put)
+              dirty_items << put_record
+              _transform_put_record(put_record, item)
+            elsif delete_record = item.delete(:delete)
+              delete_items << delete_record
+              _transform_delete_record(delete_record, item)
+            elsif update_record = item.delete(:update)
+              dirty_items << update_record
+              _transform_update_record(update_record, item)
+            elsif check_record = item.delete(:check)
+              _transform_check_record(check_record, item)
+            else
+              raise ArgumentError.new(
+                "Invalid transact write item, must include an operation of "\
+                  "type :save, :update, :delete, :update, or :check - #{item}"
+              )
+            end
+          end
+        end
+
+        def _transform_save_record(save_record, opts)
+          # determine if record is considered a new item or not
+          # then create a put with conditions, or an update
+          if save_record.send(:expect_new_item?)
+            safety_expression = save_record.send(:prevent_overwrite_expression)
+            if opts.include?(:condition_expression)
+              raise Errors::TransactionalSaveConditionCollision.new(
+                "Transactional write includes a :save operation that would "\
+                  "result in a 'safe put' for the given item, yet a "\
+                  "condition expression was also provided. This is not "\
+                  "currently supported. You should rewrite this case to use "\
+                  "a :put transaction, adding the existence check to your "\
+                  "own condition expression if desired.\n"\
+                  "\tItem: #{JSON.pretty_unparse(save_record.to_h)}\n"\
+                  "\tExtra Options: #{JSON.pretty_unparse(opts)}"
+              )
+            else
+              opts = opts.merge(safety_expression)
+              _transform_put_record(save_record, opts)
+            end
+          else
+            _transform_update_record(save_record, opts)
+          end
+        end
+
+        def _transform_put_record(put_record, opts)
+          # convert to a straight put
+          opts[:table_name] = put_record.class.table_name
+          opts[:item] = put_record.send(:_build_item_for_save)
+          { put: opts }
+        end
+
+        def _transform_delete_record(delete_record, opts)
+          # extract the key from each record to perform a deletion
+          opts[:table_name] = delete_record.class.table_name
+          opts[:key] = delete_record.send(:key_values)
+          { delete: opts }
+        end
+
+        def _transform_update_record(update_record, opts)
+          # extract dirty attribute changes to perform an update
+          opts[:table_name] = update_record.class.table_name
+          dirty_changes = update_record.send(:_dirty_changes_for_update)
+          update_tuple = update_record.class.send(
+            :_build_update_expression,
+            dirty_changes
+          )
+          uex, exp_attr_names, exp_attr_values = update_tuple
+          opts[:key] = update_record.send(:key_values)
+          opts[:update_expression] = uex
+          # need to combine expression attribute names and values
+          if names = opts[:expression_attribute_names]
+            opts[:expression_attribute_names] = exp_attr_names.merge(names)
+          else
+            opts[:expression_attribute_names] = exp_attr_names
+          end
+          if values = opts[:expression_attribute_values]
+            opts[:expression_attribute_values] = exp_attr_values.merge(values)
+          else
+            opts[:expression_attribute_values] = exp_attr_values
+          end
+          { update: opts }
+        end
+
+        def _transform_check_record(check_record, opts)
+          # check records are a pass-through
+          { condition_check: opts.merge(check_record) }
+        end
+
+        def _user_agent(custom)
+          if custom
+            custom
+          else
+            " aws-record/#{VERSION}"
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -13,6 +13,6 @@
 
 module Aws
   module Record
-    VERSION = '2.2.0'
+    VERSION = '2.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Amazon Web Services
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-12-05 00:00:00.000000000 Z
+date: 2021-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -26,7 +26,8 @@ dependencies:
         version: '1.18'
 description: Provides an object mapping abstraction for Amazon DynamoDB.
 email:
-- alexwood@amazon.com
+- mamuller@amazon.com
+- alexwoo@amazon.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -35,6 +36,7 @@ files:
 - lib/aws-record/record.rb
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
+- lib/aws-record/record/buildable_search.rb
 - lib/aws-record/record/dirty_tracking.rb
 - lib/aws-record/record/errors.rb
 - lib/aws-record/record/item_collection.rb
@@ -58,12 +60,13 @@ files:
 - lib/aws-record/record/secondary_indexes.rb
 - lib/aws-record/record/table_config.rb
 - 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
 licenses:
 - Apache 2.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -78,9 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: AWS Record library for Amazon DynamoDB
 test_files: []