dynamoid 3.11.0 → 3.13.0

data/lib/dynamoid/persistence.rb

@@ -28,9 +28,16 @@ module Dynamoid
 
     module ClassMethods
       def table_name
-        table_base_name = options[:name] || base_class.name.split('::').last.downcase.pluralize
+        return @table_name if @table_name
 
-        @table_name ||= [Dynamoid::Config.namespace.to_s, table_base_name].reject(&:empty?).join('_')
+        if options[:arn]
+          @table_name = options[:arn]
+          return @table_name
+        end
+
+        base_name = options[:name] || base_class.name.split('::').last.downcase.pluralize
+        namespace = Dynamoid::Config.namespace.to_s
+        @table_name = [namespace, base_name].reject(&:empty?).join('_')
       end
 
       # Create a table.
@@ -185,6 +192,9 @@ module Dynamoid
       #
       # Validates model and runs callbacks.
       #
+      # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but not specified or has value +nil+.
+      #
       # @param attrs [Hash|Array<Hash>] Attributes of a model
       # @param block [Proc] Block to process a document after initialization
       # @return [Dynamoid::Document] The created document
@@ -206,6 +216,9 @@ module Dynamoid
       # Raises an exception +Dynamoid::Errors::DocumentNotValid+ if validation
       # failed.
       #
+      # If any of the +before_*+ callbacks throws +:abort+ the creation is
+      # cancelled and +create!+ raises +Dynamoid::Errors::RecordNotSaved+.
+      #
       # Accepts both Hash and Array of Hashes and can create several
       # models.
       #
@@ -220,6 +233,9 @@ module Dynamoid
       #
       # Validates model and runs callbacks.
       #
+      # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but not specified or has value +nil+.
+      #
       # @param attrs [Hash|Array<Hash>] Attributes with which to create the object.
       # @param block [Proc] Block to process a document after initialization
       # @return [Dynamoid::Document] The created document
@@ -311,10 +327,16 @@ module Dynamoid
       # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
       # attributes is not on the model
       #
+      # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+      # +nil+ and +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+      # but has value +nil+.
+      #
       # @param hash_key_value [Scalar value] hash key
       # @param range_key_value [Scalar value] range key (optional)
       # @param attrs [Hash]
       # @param conditions [Hash] (optional)
+      # @option conditions [Hash] :if conditions on attribute values
+      # @option conditions [Hash] :unless_exists conditions on attributes presence
       # @return [Dynamoid::Document|nil] Updated document
       def update_fields(hash_key_value, range_key_value = nil, attrs = {}, conditions = {})
         optional_params = [range_key_value, attrs, conditions].compact
@@ -369,10 +391,16 @@ module Dynamoid
       # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
       # attributes is not declared in the model class.
       #
+      # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+      # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+      # required but has value +nil+.
+      #
       # @param hash_key_value [Scalar value] hash key
       # @param range_key_value [Scalar value] range key (optional)
       # @param attrs [Hash]
       # @param conditions [Hash] (optional)
+      # @option conditions [Hash] :if conditions on attribute values
+      # @option conditions [Hash] :unless_exists conditions on attributes presence
       # @return [Dynamoid::Document|nil] Updated document
       def upsert(hash_key_value, range_key_value = nil, attrs = {}, conditions = {})
         optional_params = [range_key_value, attrs, conditions].compact
@@ -426,9 +454,92 @@ module Dynamoid
       # @option counters [true | Symbol | Array<Symbol>] :touch to update update_at attribute and optionally the specified ones
       # @return [Model class] self
       def inc(hash_key_value, range_key_value = nil, counters)
+        # It's similar to Rails' #update_counters.
         Inc.call(self, hash_key_value, range_key_value, counters)
         self
       end
+
+      # Delete a model by a given primary key.
+      #
+      # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+      # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+      # required but has value +nil+ or is missing.
+      #
+      # @param ids [String|Array] primary key or an array of primary keys
+      # @return nil
+      #
+      # @example Delete a model by given partition key:
+      #   User.delete(user_id)
+      #
+      # @example Delete a model by given partition and sort keys:
+      #   User.delete(user_id, sort_key)
+      #
+      # @example Delete multiple models by given partition keys:
+      #   User.delete([id1, id2, id3])
+      #
+      # @example Delete multiple models by given partition and sort keys:
+      #   User.delete([[id1, sk1], [id2, sk2], [id3, sk3]])
+      def delete(*ids)
+        if ids.empty?
+          raise Dynamoid::Errors::MissingHashKey
+        end
+
+        if ids[0].is_a?(Array)
+          # given multiple keys
+          #   Model.delete([id1, id2, id3])
+          keys = ids[0] # ignore other arguments
+
+          ids = []
+          if self.range_key
+            # compound primary key
+            # expect [hash key, range key] pairs
+
+            range_key = []
+
+            # assume all elements are pairs, that's arrays
+            keys.each do |pk, sk|
+              raise Dynamoid::Errors::MissingHashKey if pk.nil?
+              raise Dynamoid::Errors::MissingRangeKey if self.range_key && sk.nil?
+
+              partition_key_dumped = cast_and_dump(hash_key, pk)
+              sort_key_dumped = cast_and_dump(self.range_key, sk)
+
+              ids << partition_key_dumped
+              range_key << sort_key_dumped
+            end
+          else
+            # simple primary key
+
+            range_key = nil
+
+            keys.each do |pk|
+              raise Dynamoid::Errors::MissingHashKey if pk.nil?
+
+              partition_key_dumped = cast_and_dump(hash_key, pk)
+              ids << partition_key_dumped
+            end
+          end
+
+          options = range_key ? { range_key: range_key } : {}
+          Dynamoid.adapter.delete(table_name, ids, options)
+        else
+          # given single primary key:
+          #   Model.delete(partition_key)
+          #   Model.delete(partition_key, sort_key)
+
+          partition_key, sort_key = ids
+
+          raise Dynamoid::Errors::MissingHashKey if partition_key.nil?
+          raise Dynamoid::Errors::MissingRangeKey if range_key? && sort_key.nil?
+
+          options = sort_key ? { range_key: cast_and_dump(self.range_key, sort_key) } : {}
+          partition_key_dumped = cast_and_dump(hash_key, partition_key)
+
+          Dynamoid.adapter.delete(table_name, partition_key_dumped, options)
+        end
+
+        nil
+      end
     end
 
     # Update document timestamps.
@@ -519,7 +630,8 @@ module Dynamoid
     # If a model is new and hash key (+id+ by default) is not assigned yet
     # it was assigned implicitly with random UUID value.
     #
-    # If +lock_version+ attribute is declared it will be incremented. If it's blank then it will be initialized with 1.
+    # If +lock_version+ attribute is declared it will be incremented. If it's
+    # blank then it will be initialized with 1.
     #
     # +save+ method call raises +Dynamoid::Errors::RecordNotUnique+ exception
     # if primary key (hash key + optional range key) already exists in a
@@ -530,6 +642,11 @@ module Dynamoid
     # already changed concurrently and +lock_version+ was consequently
     # increased.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a model is already persisted
+    # and a partition key has value +nil+ and raises
+    # +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but has
+    # value +nil+.
+    #
     # When a table is not created yet the first +save+ method call will create
     # a table. It's useful in test environment to avoid explicit table
     # creation.
@@ -553,6 +670,88 @@ module Dynamoid
       end
     end
 
+    # Create new model or persist changes.
+    #
+    # Run the validation and callbacks. Raises
+    # +Dynamoid::Errors::DocumentNotValid+ is validation fails.
+    #
+    #   user = User.create
+    #
+    #   user.age = 26
+    #   user.save! # => user
+    #
+    # Validation can be skipped with +validate: false+ option:
+    #
+    #   user = User.new(age: -1)
+    #   user.save!(validate: false) # => user
+    #
+    # If any of the +before_*+ callbacks throws +:abort+ the saving is
+    # cancelled and +save!+ raises +Dynamoid::Errors::RecordNotSaved+.
+    #
+    # +save!+ by default sets timestamps attributes - +created_at+ and
+    # +updated_at+ when creates new model and updates +updated_at+ attribute
+    # when updates already existing one.
+    #
+    # Changing +updated_at+ attribute at updating a model can be skipped with
+    # +touch: false+ option:
+    #
+    #   user.save!(touch: false)
+    #
+    # If a model is new and hash key (+id+ by default) is not assigned yet
+    # it was assigned implicitly with random UUID value.
+    #
+    # If +lock_version+ attribute is declared it will be incremented. If it's
+    # blank then it will be initialized with 1.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::RecordNotUnique+ exception
+    # if primary key (hash key + optional range key) already exists in a
+    # table.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::StaleObjectError+ exception
+    # if there is +lock_version+ attribute and the document in a table was
+    # already changed concurrently and +lock_version+ was consequently
+    # increased.
+    #
+    # +save!+ method call raises +Dynamoid::Errors::RecordNotSaved+ exception
+    # if some callback aborted execution.
+    #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a model is already persisted
+    # and a partition key has value +nil+ and raises
+    # +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but has
+    # value +nil+.
+    #
+    # When a table is not created yet the first +save!+ method call will create
+    # a table. It's useful in test environment to avoid explicit table
+    # creation.
+    #
+    # @param options [Hash] (optional)
+    # @option options [true|false] :validate validate a model or not - +true+ by default (optional)
+    # @option options [true|false] :touch update tiemstamps fields or not - +true+ by default (optional)
+    # @return [true|false] Whether saving successful or not
+    def save!(options = {})
+      # validation is handled in the Validation module
+
+      if Dynamoid.config.create_table_on_save
+        self.class.create_table(sync: true)
+      end
+
+      create_or_update = new_record? ? :create : :update
+      aborted = true
+
+      run_callbacks(:save) do
+        run_callbacks(create_or_update) do
+          aborted = false
+          Save.call(self, touch: options[:touch])
+        end
+      end
+
+      if aborted
+        raise Dynamoid::Errors::RecordNotSaved, self
+      end
+
+      self
+    end
+
     # Update multiple attributes at once, saving the object once the updates
     # are complete.
     #
@@ -564,6 +763,10 @@ module Dynamoid
     # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
     # attributes is not on the model
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @param attributes [Hash] a hash of attributes to update
     # @return [true|false] Whether updating successful or not
     # @since 0.2.0
@@ -580,9 +783,17 @@ module Dynamoid
     # Raises a +Dynamoid::Errors::DocumentNotValid+ exception if some vaidation
     # fails.
     #
+    # If any of the +before_*+ callbacks throws +:abort+ the updating is
+    # cancelled and +update_attributes!+ raises
+    # +Dynamoid::Errors::RecordNotSaved+.
+    #
     # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
     # attributes is not on the model
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @param attributes [Hash] a hash of attributes to update
     def update_attributes!(attributes)
       attributes.each { |attribute, value| write_attribute(attribute, value) }
@@ -591,8 +802,6 @@ module Dynamoid
 
     # Update a single attribute, saving the object afterwards.
     #
-    # Returns +true+ if saving is successful and +false+ otherwise.
-    #
     #   user.update_attribute(:last_name, 'Tylor')
     #
     # Validation is skipped.
@@ -607,9 +816,28 @@ module Dynamoid
     # @since 0.2.0
     def update_attribute(attribute, value)
       # final implementation is in the Dynamoid::Validation module
-      write_attribute(attribute, value)
-      save
-      self
+    end
+
+    # Update a single attribute, saving the object afterwards.
+    #
+    #   user.update_attribute!(:last_name, 'Tylor')
+    #
+    # Validation is skipped.
+    #
+    # If any of the +before_*+ callbacks throws +:abort+ the updating is
+    # cancelled and +update_attribute!+ raises
+    # +Dynamoid::Errors::RecordNotSaved+.
+    #
+    # Raises a +Dynamoid::Errors::UnknownAttribute+ exception if any of the
+    # attributes is not on the model
+    #
+    # @param attribute [Symbol] attribute name to update
+    # @param value [Object] the value to assign it
+    # @return [Dynamoid::Document] self
+    #
+    # @since 0.2.0
+    def update_attribute!(attribute, value)
+      # final implementation is in the Dynamoid::Validation module
     end
 
     # Update a model.
@@ -620,8 +848,7 @@ module Dynamoid
     # attributes. Supports following operations: +add+, +delete+ and +set+.
     #
     # Operation +add+ just adds a value for numeric attributes and join
-    # collections if attribute is a collection (one of +array+, +set+ or
-    # +map+).
+    # collections if attribute is a set.
     #
     #   user.update! do |t|
     #     t.add(age: 1, followers_count: 5)
@@ -646,7 +873,7 @@ module Dynamoid
     # {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html]
     # of +UpdateItem+ operation.
     #
-    # It's an atomic operation. So adding or deleting elements in a collection
+    # It's atomic operations. So adding or deleting elements in a collection
     # or incrementing or decrementing a numeric field is atomic and does not
     # interfere with other write requests.
     #
@@ -686,9 +913,18 @@ module Dynamoid
 
         begin
           table_name = self.class.table_name
+          partition_key_dumped = Dumping.dump_field(hash_key, self.class.attributes[self.class.hash_key])
+          conditions = conditions.dup
+          conditions[:if] ||= {}
+          conditions[:if][self.class.hash_key] = partition_key_dumped
+          if self.class.range_key
+            sort_key_dumped = Dumping.dump_field(range_value, self.class.attributes[self.class.range_key])
+            conditions[:if][self.class.range_key] = sort_key_dumped
+          end
+
           update_item_options = options.merge(conditions: conditions)
 
-          new_attrs = Dynamoid.adapter.update_item(table_name, hash_key, update_item_options) do |t|
+          new_attrs = Dynamoid.adapter.update_item(table_name, partition_key_dumped, update_item_options) do |t|
             item_updater = ItemUpdaterWithDumping.new(self.class, t)
 
             item_updater.add(lock_version: 1) if self.class.attributes[:lock_version]
@@ -701,6 +937,9 @@ module Dynamoid
           end
           load(Undumping.undump_attributes(new_attrs, self.class.attributes))
         rescue Dynamoid::Errors::ConditionalCheckFailedException
+          # exception may be raised either because of failed user provided conditions
+          # or because of conditions on partition and sort keys. We cannot
+          # distinguish these two cases.
           raise Dynamoid::Errors::StaleObjectError.new(self, 'update')
         end
       end
@@ -716,8 +955,7 @@ module Dynamoid
     # attributes. Supports following operations: +add+, +delete+ and +set+.
     #
     # Operation +add+ just adds a value for numeric attributes and join
-    # collections if attribute is a collection (one of +array+, +set+ or
-    # +map+).
+    # collections if attribute is a set.
     #
     #   user.update do |t|
     #     t.add(age: 1, followers_count: 5)
@@ -891,16 +1129,19 @@ module Dynamoid
     #
     # Returns +self+ if deleted successfully and +false+ otherwise.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @return [Dynamoid::Document|false] whether deleted successfully
     # @since 0.2.0
     def destroy
-      ret = run_callbacks(:destroy) do
+      run_callbacks(:destroy) do
         delete
+        @destroyed = true
       end
 
-      @destroyed = true
-
-      ret == false ? false : self
+      @destroyed ? self : false
     end
 
     # Delete a model.
@@ -912,6 +1153,10 @@ module Dynamoid
     #
     # Raises +Dynamoid::Errors::RecordNotDestroyed+ exception if model deleting
     # failed.
+    #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
     def destroy!
       destroy || (raise Dynamoid::Errors::RecordNotDestroyed, self)
     end
@@ -924,10 +1169,18 @@ module Dynamoid
     # Raises +Dynamoid::Errors::StaleObjectError+ exception if cannot delete a
     # model.
     #
+    # Raises +Dynamoid::Errors::MissingHashKey+ if a partition key has value
+    # +nil+ and raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is
+    # required but has value +nil+.
+    #
     # @return [Dynamoid::Document] self
     # @since 0.2.0
     def delete
+      raise Dynamoid::Errors::MissingHashKey if hash_key.nil?
+      raise Dynamoid::Errors::MissingRangeKey if self.class.range_key? && range_value.nil?
+
       options = range_key ? { range_key: Dumping.dump_field(read_attribute(range_key), self.class.attributes[range_key]) } : {}
+      partition_key_dumped = Dumping.dump_field(hash_key, self.class.attributes[self.class.hash_key])
 
       # Add an optimistic locking check if the lock_version column exists
       if self.class.attributes[:lock_version]
@@ -943,7 +1196,7 @@ module Dynamoid
 
       @destroyed = true
 
-      Dynamoid.adapter.delete(self.class.table_name, hash_key, options)
+      Dynamoid.adapter.delete(self.class.table_name, partition_key_dumped, options)
 
       self.class.associations.each_key do |name|
         send(name).disassociate_source
@@ -951,6 +1204,7 @@ module Dynamoid
 
       self
     rescue Dynamoid::Errors::ConditionalCheckFailedException
+      @destroyed = false
       raise Dynamoid::Errors::StaleObjectError.new(self, 'delete')
     end
   end

data/lib/dynamoid/transaction_read/find.rb

@@ -0,0 +1,137 @@
+# 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