dynamoid 3.13.1 → 3.14.0

data/lib/dynamoid/transactions/retrieval/find.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module Transactions
+    class Retrieval
+      # @private
+      class Find
+        attr_reader :model_class
+
+        def initialize(model_class, *ids, **options)
+          @model_class = model_class
+          @ids = ids
+          @options = options
+        end
+
+        def on_registration
+          validate_primary_key!
+        end
+
+        def observable_by_user_result
+          nil
+        end
+
+        def action_request
+          if single_key_given?
+            action_request_for_single_key
+          else
+            action_request_for_multiple_keys
+          end
+        end
+
+        def process_responses(responses)
+          models = responses.map do |response|
+            if response.item
+              @model_class.from_database(response.item)
+            elsif @options[:raise_error] == false
+              nil
+            else
+              message = build_record_not_found_exception_message(responses)
+              raise Dynamoid::Errors::RecordNotFound, message
+            end
+          end
+
+          unless single_key_given?
+            models.compact!
+          end
+
+          models.each { |m| m&.run_callbacks :find }
+          models
+        end
+
+        private
+
+        def single_key_given?
+          @ids.size == 1 && !@ids[0].is_a?(Array)
+        end
+
+        def validate_primary_key!
+          if single_key_given?
+            partition_key = @ids[0]
+            sort_key = @options[:range_key]
+
+            raise Dynamoid::Errors::MissingHashKey if partition_key.nil?
+            raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key && sort_key.nil?
+          else
+            ids = @ids.flatten(1)
+
+            raise Dynamoid::Errors::MissingHashKey if ids.any? { |pk, _sk| pk.nil? }
+            raise Errors::MissingRangeKey if @model_class.range_key && ids.any? { |_pk, sk| sk.nil? }
+          end
+        end
+
+        def action_request_for_single_key
+          partition_key = @ids[0]
+
+          key = { @model_class.hash_key => cast_and_dump_attribute(@model_class.hash_key, partition_key) }
+
+          if @model_class.range_key
+            sort_key = @options[:range_key]
+            key[@model_class.range_key] = cast_and_dump_attribute(@model_class.range_key, sort_key)
+          end
+
+          {
+            get: {
+              key: key,
+              table_name: @model_class.table_name
+            }
+          }
+        end
+
+        def action_request_for_multiple_keys
+          @ids.flatten(1).map do |id|
+            if @model_class.range_key
+              # expect [hash-key, range-key] pair
+              pk, sk = id
+              pk_dumped = cast_and_dump_attribute(@model_class.hash_key, pk)
+              sk_dumped = cast_and_dump_attribute(@model_class.range_key, sk)
+
+              key = { @model_class.hash_key => pk_dumped, @model_class.range_key => sk_dumped }
+            else
+              pk_dumped = cast_and_dump_attribute(@model_class.hash_key, id)
+
+              key = { @model_class.hash_key => pk_dumped }
+            end
+
+            {
+              get: {
+                key: key,
+                table_name: @model_class.table_name
+              }
+            }
+          end
+        end
+
+        def cast_and_dump_attribute(name, value)
+          attribute_options = @model_class.attributes[name]
+          casted_value = TypeCasting.cast_field(value, attribute_options)
+          Dumping.dump_field(casted_value, attribute_options)
+        end
+
+        def build_record_not_found_exception_message(responses)
+          items = responses.map(&:item)
+          ids = @ids.flatten(1)
+
+          if single_key_given?
+            id = ids[0]
+            primary_key = @model_class.range_key ? "(#{id.inspect},#{@options[:range_key].inspect})" : id.inspect
+            message = "Couldn't find #{@model_class.name} with primary key #{primary_key}"
+          else
+            ids_list = @model_class.range_key ? ids.map { |pk, sk| "(#{pk.inspect},#{sk.inspect})" } : ids.map(&:inspect)
+            message = "Couldn't find all #{@model_class.name.pluralize} with primary keys [#{ids_list.join(', ')}] "
+            message += "(found #{items.compact.size} results, but was looking for #{items.size})"
+          end
+
+          message
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/transactions/retrieval.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative 'retrieval/find'
+
+module Dynamoid
+  module Transactions
+    # The class +Retrieval+ 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::Transactions::Retrieval.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::Transactions::Retrieval.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 Retrieval
+      def self.execute
+        transaction = new
+
+        begin
+          yield transaction
+          transaction.commit
+        end
+      end
+
+      def initialize
+        @actions = []
+      end
+
+      # Load all the models.
+      #
+      #   transaction = Dynamoid::Transactions::Retrieval.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::Transactions::Retrieval.execute do |t|
+      #     t.find Document, 101
+      #   end
+      #
+      # @example Find by partition key and sort key
+      #   Dynamoid::Transactions::Retrieval.execute do |t|
+      #     t.find Document, 101, range_key: 'archived'
+      #   end
+      #
+      # @example Find several documents by partition key
+      #   Dynamoid::Transactions::Retrieval.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::Transactions::Retrieval.execute do |t|
+      #     t.find Document, [[101, 'archived'], [102, 'new'], [103, 'deleted']]
+      #   end
+      def find(model_class, *ids, **options)
+        action = 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
+end

data/lib/dynamoid/transactions.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'dynamoid/transactions/retrieval'
+require 'dynamoid/transactions/mutation'
+
+module Dynamoid
+  # The Transactions module provides a way to run blocks of code within a
+  # DynamoDB transaction.
+  #
+  # DynamoDB supports two types of transactions: read-only and write-only.
+  # This module provides a unified interface to both.
+  #
+  # @example Rails-style transaction (defaults to write)
+  #   User.transaction do |t|
+  #     t.save(user)
+  #     t.create(Account, name: 'A')
+  #   end
+  #
+  # @example Explicit write transaction
+  #   User.transaction.writing do |t|
+  #     t.save(user)
+  #     t.create(Account, name: 'A')
+  #   end
+  #
+  # @example Explicit read transaction
+  #   users = User.transaction.reading do |t|
+  #     t.find(User, '1')
+  #     t.find(User, '2')
+  #   end
+  module Transactions
+    extend ActiveSupport::Concern
+
+    # Proxy object to provide .writing and .reading methods on .transaction
+    class Proxy
+      def writing(&block)
+        Mutation.execute(&block)
+      end
+
+      def reading(&block)
+        Retrieval.execute(&block)
+      end
+    end
+
+    module ClassMethods
+      # Start a transaction.
+      #
+      # If a block is given, it starts a write transaction.
+      #
+      # If no block is given, it returns a proxy object that supports
+      # .writing and .reading methods.
+      #
+      # @param block [Proc] optional block to run in a write transaction
+      # @return [Proxy|nil|Array<Dynamoid::Document>]
+      def transaction(&block)
+        if block_given?
+          Mutation.execute(&block)
+        else
+          Proxy.new
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dynamoid
-  VERSION = '3.13.1'
+  VERSION = '3.14.0'
 end

data/lib/dynamoid.rb

@@ -32,11 +32,10 @@ require 'dynamoid/finders'
 require 'dynamoid/identity_map'
 require 'dynamoid/config'
 require 'dynamoid/loadable'
+require 'dynamoid/transactions'
 require 'dynamoid/components'
 require 'dynamoid/document'
 require 'dynamoid/adapter'
-require 'dynamoid/transaction_read'
-require 'dynamoid/transaction_write'
 
 require 'dynamoid/tasks/database'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamoid
 version: !ruby/object:Gem::Version
-  version: 3.13.1
+  version: 3.14.0
 platform: ruby
 authors:
 - Josh Symonds
@@ -241,19 +241,25 @@ files:
 - lib/dynamoid/tasks.rb
 - lib/dynamoid/tasks/database.rake
 - lib/dynamoid/tasks/database.rb
-- lib/dynamoid/transaction_read.rb
-- lib/dynamoid/transaction_read/find.rb
-- lib/dynamoid/transaction_write.rb
-- lib/dynamoid/transaction_write/base.rb
-- lib/dynamoid/transaction_write/create.rb
-- lib/dynamoid/transaction_write/delete_with_instance.rb
-- lib/dynamoid/transaction_write/delete_with_primary_key.rb
-- lib/dynamoid/transaction_write/destroy.rb
-- lib/dynamoid/transaction_write/item_updater.rb
-- lib/dynamoid/transaction_write/save.rb
-- lib/dynamoid/transaction_write/update_attributes.rb
-- lib/dynamoid/transaction_write/update_fields.rb
-- lib/dynamoid/transaction_write/upsert.rb
+- lib/dynamoid/transactions.rb
+- lib/dynamoid/transactions/mutation.rb
+- lib/dynamoid/transactions/mutation/base.rb
+- lib/dynamoid/transactions/mutation/builders/delete_request_builder.rb
+- lib/dynamoid/transactions/mutation/builders/update_request_builder.rb
+- lib/dynamoid/transactions/mutation/create.rb
+- lib/dynamoid/transactions/mutation/delete_with_instance.rb
+- lib/dynamoid/transactions/mutation/delete_with_primary_key.rb
+- lib/dynamoid/transactions/mutation/destroy.rb
+- lib/dynamoid/transactions/mutation/import.rb
+- lib/dynamoid/transactions/mutation/inc.rb
+- lib/dynamoid/transactions/mutation/increment.rb
+- lib/dynamoid/transactions/mutation/save.rb
+- lib/dynamoid/transactions/mutation/touch.rb
+- lib/dynamoid/transactions/mutation/update_attributes.rb
+- lib/dynamoid/transactions/mutation/update_fields.rb
+- lib/dynamoid/transactions/mutation/upsert.rb
+- lib/dynamoid/transactions/retrieval.rb
+- lib/dynamoid/transactions/retrieval/find.rb
 - lib/dynamoid/type_casting.rb
 - lib/dynamoid/undumping.rb
 - lib/dynamoid/validations.rb
@@ -263,10 +269,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: http://github.com/Dynamoid/dynamoid
-  source_code_uri: https://github.com/Dynamoid/dynamoid/tree/v3.13.1
-  changelog_uri: https://github.com/Dynamoid/dynamoid/blob/v3.13.1/CHANGELOG.md
+  source_code_uri: https://github.com/Dynamoid/dynamoid/tree/v3.14.0
+  changelog_uri: https://github.com/Dynamoid/dynamoid/blob/v3.14.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/Dynamoid/dynamoid/issues
-  documentation_uri: https://www.rubydoc.info/gems/dynamoid/3.13.1
+  documentation_uri: https://www.rubydoc.info/gems/dynamoid/3.14.0
   funding_uri: https://opencollective.com/dynamoid
   wiki_uri: https://github.com/Dynamoid/dynamoid/wiki
   rubygems_mfa_required: 'true'

data/lib/dynamoid/transaction_read/find.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Dynamoid
-  class TransactionRead
-    class Find
-      attr_reader :model_class
-
-      def initialize(model_class, *ids, **options)
-        @model_class = model_class
-        @ids = ids
-        @options = options
-      end
-
-      def on_registration
-        validate_primary_key!
-      end
-
-      def observable_by_user_result
-        nil
-      end
-
-      def action_request
-        if single_key_given?
-          action_request_for_single_key
-        else
-          action_request_for_multiple_keys
-        end
-      end
-
-      def process_responses(responses)
-        models = responses.map do |response|
-          if response.item
-            @model_class.from_database(response.item)
-          elsif @options[:raise_error] == false
-            nil
-          else
-            message = build_record_not_found_exception_message(responses)
-            raise Dynamoid::Errors::RecordNotFound, message
-          end
-        end
-
-        unless single_key_given?
-          models.compact!
-        end
-
-        models.each { |m| m&.run_callbacks :find }
-        models
-      end
-
-      private
-
-      def single_key_given?
-        @ids.size == 1 && !@ids[0].is_a?(Array)
-      end
-
-      def validate_primary_key!
-        if single_key_given?
-          partition_key = @ids[0]
-          sort_key = @options[:range_key]
-
-          raise Dynamoid::Errors::MissingHashKey if partition_key.nil?
-          raise Dynamoid::Errors::MissingRangeKey if @model_class.range_key && sort_key.nil?
-        else
-          ids = @ids.flatten(1)
-
-          raise Dynamoid::Errors::MissingHashKey if ids.any? { |pk, _sk| pk.nil? }
-          raise Errors::MissingRangeKey if @model_class.range_key && ids.any? { |_pk, sk| sk.nil? }
-        end
-      end
-
-      def action_request_for_single_key
-        partition_key = @ids[0]
-
-        key = { @model_class.hash_key => cast_and_dump_attribute(@model_class.hash_key, partition_key) }
-
-        if @model_class.range_key
-          sort_key = @options[:range_key]
-          key[@model_class.range_key] = cast_and_dump_attribute(@model_class.range_key, sort_key)
-        end
-
-        {
-          get: {
-            key: key,
-            table_name: @model_class.table_name
-          }
-        }
-      end
-
-      def action_request_for_multiple_keys
-        @ids.flatten(1).map do |id|
-          if @model_class.range_key
-            # expect [hash-key, range-key] pair
-            pk, sk = id
-            pk_dumped = cast_and_dump_attribute(@model_class.hash_key, pk)
-            sk_dumped = cast_and_dump_attribute(@model_class.range_key, sk)
-
-            key = { @model_class.hash_key => pk_dumped, @model_class.range_key => sk_dumped }
-          else
-            pk_dumped = cast_and_dump_attribute(@model_class.hash_key, id)
-
-            key = { @model_class.hash_key => pk_dumped }
-          end
-
-          {
-            get: {
-              key: key,
-              table_name: @model_class.table_name
-            }
-          }
-        end
-      end
-
-      def cast_and_dump_attribute(name, value)
-        attribute_options = @model_class.attributes[name]
-        casted_value = TypeCasting.cast_field(value, attribute_options)
-        Dumping.dump_field(casted_value, attribute_options)
-      end
-
-      def build_record_not_found_exception_message(responses)
-        items = responses.map(&:item)
-        ids = @ids.flatten(1)
-
-        if single_key_given?
-          id = ids[0]
-          primary_key = @model_class.range_key ? "(#{id.inspect},#{@options[:range_key].inspect})" : id.inspect
-          message = "Couldn't find #{@model_class.name} with primary key #{primary_key}"
-        else
-          ids_list = @model_class.range_key ? ids.map { |pk, sk| "(#{pk.inspect},#{sk.inspect})" } : ids.map(&:inspect)
-          message = "Couldn't find all #{@model_class.name.pluralize} with primary keys [#{ids_list.join(', ')}] "
-          message += "(found #{items.compact.size} results, but was looking for #{items.size})"
-        end
-
-        message
-      end
-    end
-  end
-end