dynamoid 3.11.0 → 3.12.1

data/lib/dynamoid/transaction_read.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'dynamoid/transaction_read/find'
+
+module Dynamoid
+  # The class +TransactionRead+ provides means to perform multiple reading
+  # operations in transaction, that is atomically, so that either all of them
+  # succeed, or all of them fail.
+  #
+  # The reading methods are supposed to be as close as possible to their
+  # non-transactional counterparts:
+  #
+  #   user_id = params[:user_id]
+  #   payment = params[:payment_id]
+  #
+  #   models = Dynamoid::TransactionRead.execute do |t|
+  #     t.find User, user_id
+  #     t.find Payment, payment_id
+  #   end
+  #
+  # The only difference is that the methods are called on a transaction
+  # instance and a model or a model class should be specified. So +User.find+
+  # becomes +t.find(user_id)+ and +Payment.find(payment_id)+ becomes +t.find
+  # Payment, payment_id+.
+  #
+  # A transaction can be used without a block. This way a transaction instance
+  # should be instantiated and committed manually with +#commit+ method:
+  #
+  #   t = Dynamoid::TransactionRead.new
+  #
+  #   t.find user_id
+  #   t.find payment_id
+  #
+  #   models = t.commit
+  #
+  #
+  # ### DynamoDB's transactions
+  #
+  # The main difference between DynamoDB transactions and a common interface is
+  # that DynamoDB's transactions are executed in batch. So in Dynamoid no
+  # data actually loaded when some transactional method (e.g+ `#find+) is
+  # called. All the changes are loaded at the end.
+  #
+  # A +TransactGetItems+ DynamoDB operation is used (see
+  # [documentation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
+  # for details).
+  class TransactionRead
+    def self.execute
+      transaction = new
+
+      begin
+        yield transaction
+        transaction.commit
+      end
+    end
+
+    def initialize
+      @actions = []
+    end
+
+    # Load all the models.
+    #
+    #   transaction = Dynamoid::TransactionRead.new
+    #   # ...
+    #   transaction.commit
+    def commit
+      return [] if @actions.empty?
+
+      # some actions may produce multiple requests
+      action_request_groups = @actions.map(&:action_request).map do |action_request|
+        action_request.is_a?(Array) ? action_request : [action_request]
+      end
+      action_requests = action_request_groups.flatten(1)
+
+      return [] if action_requests.empty?
+
+      response = Dynamoid.adapter.transact_read_items(action_requests)
+
+      responses = response.responses.dup
+      @actions.zip(action_request_groups).map do |action, action_requests|
+        action_responses = responses.shift(action_requests.size)
+        action.process_responses(action_responses)
+      end.flatten
+    end
+
+    # Find one or many objects, specified by one id or an array of ids.
+    #
+    # By default it raises +RecordNotFound+ exception if at least one model
+    # isn't found. This behavior can be changed with +raise_error+ option. If
+    # specified +raise_error: false+ option then +find+ will not raise the
+    # exception.
+    #
+    # When a document schema includes range key it should always be specified
+    # in +find+ method call. In case it's missing +MissingRangeKey+ exception
+    # will be raised.
+    #
+    # Please note that there are the following differences between
+    # transactional and non-transactional +find+:
+    # - transactional +find+ preserves order of models in result when given multiple ids
+    # - transactional +find+ doesn't return results immediately, a single
+    #   collection with results of all the +find+ calls is returned instead
+    # - +:consistent_read+ option isn't supported
+    # - transactional +find+ is subject to limitations of the
+    #   [TransactGetItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)
+    #   DynamoDB operation, e.g. the whole read transaction can load only up to 100 models.
+    #
+    # @param [Object|Array] ids a single primary key or an array of primary keys
+    # @param [Hash] options optional parameters of the operation
+    # @option options [Object] :range_key sort key of a model; required when a single partition key is given and a sort key is declared for a model
+    # @option options [true|false] :raise_error whether to raise a +RecordNotFound+ exception; specify explicitly +raise_error: false+ to suppress the exception; default is +true+
+    # @return [nil]
+    #
+    # @example Find by partition key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101
+    #   end
+    #
+    # @example Find by partition key and sort key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101, range_key: 'archived'
+    #   end
+    #
+    # @example Find several documents by partition key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, 101, 102, 103
+    #     t.find Document, [101, 102, 103]
+    #   end
+    #
+    # @example Find several documents by partition key and sort key
+    #   Dynamoid::TransactionRead.execute do |t|
+    #     t.find Document, [[101, 'archived'], [102, 'new'], [103, 'deleted']]
+    #   end
+    def find(model_class, *ids, **options)
+      action = Dynamoid::TransactionRead::Find.new(model_class, *ids, **options)
+      register_action action
+    end
+
+    private
+
+    def register_action(action)
+      @actions << action
+      action.on_registration
+      action.observable_by_user_result
+    end
+  end
+end

data/lib/dynamoid/transaction_write/delete_with_instance.rb

@@ -35,10 +35,10 @@ module Dynamoid
       end
 
       def action_request
-        key = { @model_class.hash_key => @model.hash_key }
+        key = { @model_class.hash_key => dump_attribute(@model_class.hash_key, @model.hash_key) }
 
         if @model_class.range_key?
-          key[@model_class.range_key] = @model.range_value
+          key[@model_class.range_key] = dump_attribute(@model_class.range_key, @model.range_value)
         end
 
         {
@@ -55,6 +55,11 @@ module Dynamoid
         raise Dynamoid::Errors::MissingHashKey if @model.hash_key.nil?
         raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key? && @model.range_value.nil?
       end
+
+      def dump_attribute(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
     end
   end
 end

data/lib/dynamoid/transaction_write/delete_with_primary_key.rb

@@ -34,10 +34,10 @@ module Dynamoid
       end
 
       def action_request
-        key = { @model_class.hash_key => @hash_key }
+        key = { @model_class.hash_key => dump_attribute(@model_class.hash_key, @hash_key) }
 
         if @model_class.range_key?
-          key[@model_class.range_key] = @range_key
+          key[@model_class.range_key] = dump_attribute(@model_class.range_key, @range_key)
         end
 
         {
@@ -54,6 +54,11 @@ module Dynamoid
         raise Dynamoid::Errors::MissingHashKey if @hash_key.nil?
         raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key? && @range_key.nil?
       end
+
+      def dump_attribute(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
     end
   end
 end

data/lib/dynamoid/transaction_write/destroy.rb

@@ -54,10 +54,10 @@ module Dynamoid
       end
 
       def action_request
-        key = { @model_class.hash_key => @model.hash_key }
+        key = { @model_class.hash_key => dump_attribute(@model_class.hash_key, @model.hash_key) }
 
         if @model_class.range_key?
-          key[@model_class.range_key] = @model.range_value
+          key[@model_class.range_key] = dump_attribute(@model_class.range_key, @model.range_value)
         end
 
         {
@@ -74,6 +74,11 @@ module Dynamoid
         raise Dynamoid::Errors::MissingHashKey if @model.hash_key.nil?
         raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key? && @model.range_value.nil?
       end
+
+      def dump_attribute(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
     end
   end
 end

data/lib/dynamoid/transaction_write/item_updater.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  class TransactionWrite
+    class ItemUpdater
+      attr_reader :attributes_to_set, :attributes_to_add, :attributes_to_delete, :attributes_to_remove
+
+      def initialize(model_class)
+        @model_class = model_class
+
+        @attributes_to_set = {}
+        @attributes_to_add = {}
+        @attributes_to_delete = {}
+        @attributes_to_remove = []
+      end
+
+      def empty?
+        [@attributes_to_set, @attributes_to_add, @attributes_to_delete, @attributes_to_remove].all?(&:empty?)
+      end
+
+      def set(attributes)
+        validate_attribute_names!(attributes.keys)
+        @attributes_to_set.merge!(attributes)
+      end
+
+      # adds to array of fields for use in REMOVE update expression
+      def remove(*names)
+        validate_attribute_names!(names)
+        @attributes_to_remove += names
+      end
+
+      # increments a number or adds to a set, starts at 0 or [] if it doesn't yet exist
+      def add(attributes)
+        validate_attribute_names!(attributes.keys)
+        @attributes_to_add.merge!(attributes)
+      end
+
+      # deletes a value or values from a set
+      def delete(attributes)
+        validate_attribute_names!(attributes.keys)
+        @attributes_to_delete.merge!(attributes)
+      end
+
+      private
+
+      def validate_attribute_names!(names)
+        names.each do |name|
+          unless @model_class.attributes[name]
+            raise Dynamoid::Errors::UnknownAttribute.new(@model_class, name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/transaction_write/save.rb

@@ -121,8 +121,8 @@ module Dynamoid
         changes_dumped = Dynamoid::Dumping.dump_attributes(changes, @model_class.attributes)
 
         # primary key to look up an item to update
-        key = { @model_class.hash_key => @model.hash_key }
-        key[@model_class.range_key] = @model.range_value if @model_class.range_key?
+        key = { @model_class.hash_key => dump_attribute(@model_class.hash_key, @model.hash_key) }
+        key[@model_class.range_key] = dump_attribute(@model_class.range_key, @model.range_value) if @model_class.range_key?
 
         # Build UpdateExpression and keep names and values placeholders mapping
         # in ExpressionAttributeNames and ExpressionAttributeValues.
@@ -159,6 +159,11 @@ module Dynamoid
         @model.updated_at = timestamp unless @options[:touch] == false && !@was_new_record
         @model.created_at ||= timestamp unless skip_created_at
       end
+
+      def dump_attribute(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
     end
   end
 end

data/lib/dynamoid/transaction_write/update_fields.rb

@@ -6,18 +6,24 @@ require 'dynamoid/persistence/update_validations'
 module Dynamoid
   class TransactionWrite
     class UpdateFields < Base
-      def initialize(model_class, hash_key, range_key, attributes)
+      def initialize(model_class, hash_key, range_key, attributes, &block)
         super()
 
         @model_class = model_class
         @hash_key = hash_key
         @range_key = range_key
-        @attributes = attributes
+        @attributes = attributes || {}
+        @block = block
       end
 
       def on_registration
         validate_primary_key!
         Dynamoid::Persistence::UpdateValidations.validate_attributes_exist(@model_class, @attributes)
+
+        if @block
+          @item_updater = ItemUpdater.new(@model_class)
+          @block.call(@item_updater)
+        end
       end
 
       def on_commit; end
@@ -29,7 +35,7 @@ module Dynamoid
       end
 
       def skipped?
-        @attributes.empty?
+        @attributes.empty? && (!@item_updater || @item_updater.empty?)
       end
 
       def observable_by_user_result
@@ -37,48 +43,55 @@ module Dynamoid
       end
 
       def action_request
+        builder = UpdateRequestBuilder.new(@model_class)
+
+        # primary key to look up an item to update
+        builder.hash_key = dump_attribute(@model_class.hash_key, @hash_key)
+        builder.range_key = dump_attribute(@model_class.range_key, @range_key) if @model_class.range_key?
+
         # changed attributes to persist
         changes = @attributes.dup
         changes = add_timestamps(changes, skip_created_at: true)
         changes_dumped = Dynamoid::Dumping.dump_attributes(changes, @model_class.attributes)
 
-        # primary key to look up an item to update
-        key = { @model_class.hash_key => @hash_key }
-        key[@model_class.range_key] = @range_key if @model_class.range_key?
-
-        # Build UpdateExpression and keep names and values placeholders mapping
-        # in ExpressionAttributeNames and ExpressionAttributeValues.
-        update_expression_statements = []
-        expression_attribute_names = {}
-        expression_attribute_values = {}
-
-        changes_dumped.each_with_index do |(name, value), i|
-          name_placeholder = "#_n#{i}"
-          value_placeholder = ":_s#{i}"
-
-          update_expression_statements << "#{name_placeholder} = #{value_placeholder}"
-          expression_attribute_names[name_placeholder] = name
-          expression_attribute_values[value_placeholder] = value
+        builder.set_attributes(changes_dumped)
+
+        # given a block
+        if @item_updater
+          builder.set_attributes(@item_updater.attributes_to_set)
+          builder.remove_attributes(@item_updater.attributes_to_remove)
+
+          @item_updater.attributes_to_add.each do |name, value|
+            # The ADD section in UpdateExpressions requires values to be a
+            # set to update a set attribute.
+            # Allow specifying values as any Enumerable collection (e.g. Array).
+            # Allow a single value not wrapped into a Set
+            if @model_class.attributes[name][:type] == :set
+              value = value.is_a?(Enumerable) ? Set.new(value) : Set[value]
+            end
+
+            builder.add_value(name, value)
+          end
+
+          @item_updater.attributes_to_delete.each do |name, value|
+            # The DELETE section in UpdateExpressions requires values to be a
+            # set to update a set attribute.
+            # Allow specifying values as any Enumerable collection (e.g. Array).
+            # Allow a single value not wrapped into a Set
+            value = value.is_a?(Enumerable) ? Set.new(value) : Set[value]
+
+            builder.delete_value(name, value)
+          end
         end
 
-        update_expression = "SET #{update_expression_statements.join(', ')}"
-
         # require primary key to exist
         condition_expression = "attribute_exists(#{@model_class.hash_key})"
         if @model_class.range_key?
           condition_expression += " AND attribute_exists(#{@model_class.range_key})"
         end
+        builder.condition_expression = condition_expression
 
-        {
-          update: {
-            key: key,
-            table_name: @model_class.table_name,
-            update_expression: update_expression,
-            expression_attribute_names: expression_attribute_names,
-            expression_attribute_values: expression_attribute_values,
-            condition_expression: condition_expression
-          }
-        }
+        builder.request
       end
 
       private
@@ -97,6 +110,130 @@ module Dynamoid
         result[:updated_at] ||= timestamp
         result
       end
+
+      def dump_attribute(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
+
+      class UpdateRequestBuilder
+        attr_writer :hash_key, :range_key, :condition_expression
+
+        def initialize(model_class)
+          @model_class = model_class
+
+          @attributes_to_set = {}
+          @attributes_to_add = {}
+          @attributes_to_delete = {}
+          @attributes_to_remove = []
+          @condition_expression = nil
+        end
+
+        def set_attributes(attributes) # rubocop:disable Naming/AccessorMethodName
+          @attributes_to_set.merge!(attributes)
+        end
+
+        def add_value(name, value)
+          @attributes_to_add[name] = value
+        end
+
+        def delete_value(name, value)
+          @attributes_to_delete[name] = value
+        end
+
+        def remove_attributes(names)
+          @attributes_to_remove.concat(names)
+        end
+
+        def request
+          key = { @model_class.hash_key => @hash_key }
+          key[@model_class.range_key] = @range_key if @model_class.range_key?
+
+          # Build UpdateExpression and keep names and values placeholders mapping
+          # in ExpressionAttributeNames and ExpressionAttributeValues.
+          update_expression_statements = []
+          expression_attribute_names = {}
+          expression_attribute_values = {}
+          name_placeholder = '#_n0'
+          value_placeholder = ':_v0'
+
+          unless @attributes_to_set.empty?
+            statements = []
+
+            @attributes_to_set.each do |name, value|
+              statements << "#{name_placeholder} = #{value_placeholder}"
+
+              expression_attribute_names[name_placeholder] = name
+              expression_attribute_values[value_placeholder] = value
+
+              name_placeholder = name_placeholder.succ
+              value_placeholder = value_placeholder.succ
+            end
+
+            update_expression_statements << "SET #{statements.join(', ')}"
+          end
+
+          unless @attributes_to_add.empty?
+            statements = []
+
+            @attributes_to_add.each do |name, value|
+              statements << "#{name_placeholder} #{value_placeholder}"
+
+              expression_attribute_names[name_placeholder] = name
+              expression_attribute_values[value_placeholder] = value
+
+              name_placeholder = name_placeholder.succ
+              value_placeholder = value_placeholder.succ
+            end
+
+            update_expression_statements << "ADD #{statements.join(', ')}"
+          end
+
+          unless @attributes_to_delete.empty?
+            statements = []
+
+            @attributes_to_delete.each do |name, value|
+              statements << "#{name_placeholder} #{value_placeholder}"
+
+              expression_attribute_names[name_placeholder] = name
+              expression_attribute_values[value_placeholder] = value
+
+              name_placeholder = name_placeholder.succ
+              value_placeholder = value_placeholder.succ
+            end
+
+            update_expression_statements << "DELETE #{statements.join(', ')}"
+          end
+
+          unless @attributes_to_remove.empty?
+            name_placeholders = []
+
+            @attributes_to_remove.each do |name|
+              name_placeholders << name_placeholder
+
+              expression_attribute_names[name_placeholder] = name
+
+              name_placeholder = name_placeholder.succ
+              value_placeholder = value_placeholder.succ
+            end
+
+            update_expression_statements << "REMOVE #{name_placeholders.join(', ')}"
+          end
+
+          update_expression = update_expression_statements.join(' ')
+
+          {
+            update: {
+              key: key,
+              table_name: @model_class.table_name,
+              update_expression: update_expression,
+              expression_attribute_names: expression_attribute_names,
+              expression_attribute_values: expression_attribute_values,
+              condition_expression: @condition_expression
+            }
+          }
+        end
+      end
     end
   end
 end

data/lib/dynamoid/transaction_write/upsert.rb

@@ -44,8 +44,13 @@ module Dynamoid
         changes_dumped = Dynamoid::Dumping.dump_attributes(changes, @model_class.attributes)
 
         # primary key to look up an item to update
-        key = { @model_class.hash_key => @hash_key }
-        key[@model_class.range_key] = @range_key if @model_class.range_key?
+        partition_key_dumped = dump(@model_class.hash_key, @hash_key)
+        key = { @model_class.hash_key => partition_key_dumped }
+
+        if @model_class.range_key?
+          sort_key_dumped = dump(@model_class.range_key, @range_key)
+          key[@model_class.range_key] = sort_key_dumped
+        end
 
         # Build UpdateExpression and keep names and values placeholders mapping
         # in ExpressionAttributeNames and ExpressionAttributeValues.
@@ -91,6 +96,11 @@ module Dynamoid
         result[:updated_at] ||= timestamp
         result
       end
+
+      def dump(name, value)
+        options = @model_class.attributes[name]
+        Dumping.dump_field(value, options)
+      end
     end
   end
 end