dynamoid 3.11.0 → 3.12.1

data/lib/dynamoid/transaction_write.rb

@@ -8,6 +8,7 @@ require 'dynamoid/transaction_write/save'
 require 'dynamoid/transaction_write/update_fields'
 require 'dynamoid/transaction_write/update_attributes'
 require 'dynamoid/transaction_write/upsert'
+require 'dynamoid/transaction_write/item_updater'
 
 module Dynamoid
   # The class +TransactionWrite+ provides means to perform multiple modifying
@@ -177,6 +178,26 @@ module Dynamoid
     # When a model is not persisted - its id should have unique value.
     # Otherwise a transaction will be rolled back.
     #
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#save!+:
+    # - transactional +#save!+ doesn't support the +:touch+ option
+    # - transactional +#save!+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#save!+ doesn't raise +Dynamoid::Errors::RecordNotUnique+
+    #   at saving new model when primary key is already used. A generic
+    #   +Aws::DynamoDB::Errors::TransactionCanceledException+ is raised instead.
+    # - transactional +save!+ doesn't raise
+    #   +Dynamoid::Errors::StaleObjectError+ when a model that is being updated
+    #   was concurrently deleted
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model [Dynamoid::Document] a model
     # @param options [Hash] (optional)
     # @option options [true|false] :validate validate a model or not - +true+ by default (optional)
@@ -215,6 +236,25 @@ module Dynamoid
     # When a model is not persisted - its id should have unique value.
     # Otherwise a transaction will be rolled back.
     #
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#save+:
+    # - transactional +#save+ doesn't support the +:touch+ option
+    # - transactional +#save+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#save+ doesn't raise +Dynamoid::Errors::RecordNotUnique+
+    #   at saving new model when primary key is already used. A generic
+    #   +Aws::DynamoDB::Errors::TransactionCanceledException+ is raised instead.
+    # - transactional +save+ doesn't raise +Dynamoid::Errors::StaleObjectError+
+    #   when a model that is being updated was concurrently deleted
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model [Dynamoid::Document] a model
     # @param options [Hash] (optional)
     # @option options [true|false] :validate validate a model or not - +true+ by default (optional)
@@ -247,6 +287,20 @@ module Dynamoid
     #
     # Validates model and runs callbacks.
     #
+    # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but
+    # not specified or has value +nil+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#create+:
+    # - transactional +#create!+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#create!+ doesn't raise +Dynamoid::Errors::RecordNotUnique+
+    #   at saving new model when primary key is already used. A generic
+    #   +Aws::DynamoDB::Errors::TransactionCanceledException+ is raised instead.
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model_class [Class] a model class which should be instantiated
     # @param attributes [Hash|Array<Hash>] attributes of a model
     # @param block [Proc] a block to process a model after initialization
@@ -286,6 +340,20 @@ module Dynamoid
     #
     # Validates model and runs callbacks.
     #
+    # Raises +Dynamoid::Errors::MissingRangeKey+ if a sort key is required but
+    # not specified or has value +nil+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#create+:
+    # - transactional +#create+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#create+ doesn't raise +Dynamoid::Errors::RecordNotUnique+
+    #   at saving new model when primary key is already used. A generic
+    #   +Aws::DynamoDB::Errors::TransactionCanceledException+ is raised instead.
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model_class [Class] a model class which should be instantiated
     # @param attributes [Hash|Array<Hash>] attributes of a model
     # @param block [Proc] a block to process a model after initialization
@@ -321,6 +389,17 @@ 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 +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+    # but has value +nil+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#upsert+:
+    # - transactional +#upsert+ doesn't support conditions (that's +if+ and
+    #   +unless_exists+ options)
+    # - transactional +#upsert+ doesn't return a document that was updated or
+    #   created
+    #
     # @param model_class [Class] a model class
     # @param hash_key [Scalar value] hash key value
     # @param range_key [Scalar value] range key value (optional)
@@ -345,16 +424,79 @@ module Dynamoid
     #     t.update_fields(User, '1', 'Tylor', age: 26)
     #   end
     #
+    # Updates can also be performed in a block.
+    #
+    #   Dynamoid::TransactionWrite.execute do |t|
+    #     t.update_fields(User, 1) do |u|
+    #       u.add(article_count: 1)
+    #       u.delete(favorite_colors: 'green')
+    #       u.set(age: 27, last_name: 'Tylor')
+    #     end
+    #   end
+    #
+    # Operation +add+ just adds a value for numeric attributes and join
+    # collections if attribute is a set.
+    #
+    #   t.update_fields(User, 1) do |u|
+    #     u.add(age: 1, followers_count: 5)
+    #     u.add(hobbies: ['skying', 'climbing'])
+    #   end
+    #
+    # Operation +delete+ is applied to collection attribute types and
+    # substructs one collection from another.
+    #
+    #   t.update_fields(User, 1) do |u|
+    #     u.delete(hobbies: ['skying'])
+    #   end
+    #
+    # Operation +set+ just changes an attribute value:
+    #
+    #   t.update_fields(User, 1) do |u|
+    #     u.set(age: 21)
+    #   end
+    #
+    # Operation +remove+ removes one or more attributes from an item.
+    #
+    #   t.update_fields(User, 1) do |u|
+    #     u.remove(:age)
+    #   end
+    #
+    # All the operations work like +ADD+, +DELETE+, +REMOVE+, and +SET+ actions supported
+    # by +UpdateExpression+
+    # {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html]
+    # of +UpdateItem+ operation.
+    #
+    # 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.
+    #
     # 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 +Dynamoid::Errors::MissingRangeKey+ if a sort key is required
+    # but has value +nil+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#update_fields+:
+    # - transactional +#update_fields+ doesn't support conditions (that's +if+
+    #   and +unless_exists+ options)
+    # - transactional +#update_fields+ doesn't return a document that was
+    #   updated or created
+    #
     # @param model_class [Class] a model class
     # @param hash_key [Scalar value] hash key value
     # @param range_key [Scalar value] range key value (optional)
     # @param attributes [Hash]
     # @return [nil]
-    def update_fields(model_class, hash_key, range_key = nil, attributes) # rubocop:disable Style/OptionalArguments
-      action = Dynamoid::TransactionWrite::UpdateFields.new(model_class, hash_key, range_key, attributes)
+    def update_fields(model_class, hash_key, range_key = nil, attributes = nil, &block)
+      # given no attributes, but there may be a block
+      if range_key.is_a?(Hash) && !attributes
+        attributes = range_key
+        range_key = nil
+      end
+
+      action = Dynamoid::TransactionWrite::UpdateFields.new(model_class, hash_key, range_key, attributes, &block)
       register_action action
     end
 
@@ -367,6 +509,21 @@ module Dynamoid
     # Returns +true+ if saving is successful 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#update_attributes+:
+    # - transactional +#update_attributes+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +update_attributes+ doesn't raise
+    #   +Dynamoid::Errors::StaleObjectError+ when a model that is being updated
+    #   was concurrently deleted
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model [Dynamoid::Document] a model
     # @param attributes [Hash] a hash of attributes to update
     # @return [true|false] Whether updating successful or not
@@ -387,6 +544,21 @@ module Dynamoid
     # Raises a +Dynamoid::Errors::DocumentNotValid+ exception if some vaidation
     # fails.
     #
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#update_attributes!+:
+    # - transactional +#update_attributes!+ doesn't support +lock_version+
+    #   attribute so it will not be incremented and will not be checked to detect
+    #   concurrent modification of a model and
+    #   +Dynamoid::Errors::StaleObjectError+ exception will not be raised
+    # - transactional +update_attributes!+ doesn't raise
+    #   +Dynamoid::Errors::StaleObjectError+ when a model that is being updated
+    #   was concurrently deleted
+    # - a table isn't created lazily if it doesn't exist yet
+    #
     # @param model [Dynamoid::Document] a model
     # @param attributes [Hash] a hash of attributes to update
     def update_attributes!(model, attributes)
@@ -408,7 +580,18 @@ module Dynamoid
     #     t.delete(User, user_id)
     #   end
     #
-    # Raise +MissingRangeKey+ if a range key is declared but not passed as argument.
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#delete+: TBD
+    # - transactional +#delete+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#delete+ doesn't disassociate a model from associated ones
+    #   if there is any
     #
     # @param model_or_model_class [Class|Dynamoid::Document] either model or model class
     # @param hash_key [Scalar value] hash key value
@@ -430,6 +613,19 @@ module Dynamoid
     # Raises +Dynamoid::Errors::RecordNotDestroyed+ exception if model deleting
     # failed (e.g. aborted by a callback).
     #
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#destroy!+:
+    # - transactional +#destroy!+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#destroy!+ doesn't disassociate a model from associated ones
+    #   if there are association declared in the model class
+    #
     # @param model [Dynamoid::Document] a model
     # @return [Dynamoid::Document|false] returns self if destoying is succefull, +false+ otherwise
     def destroy!(model)
@@ -441,6 +637,19 @@ module Dynamoid
     #
     # Runs callbacks.
     #
+    # 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+.
+    #
+    # There are the following differences between transactional and
+    # non-transactional +#destroy+:
+    # - transactional +#destroy+ doesn't support +lock_version+ attribute so it
+    #   will not be incremented and will not be checked to detect concurrent
+    #   modification of a model and +Dynamoid::Errors::StaleObjectError+
+    #   exception will not be raised
+    # - transactional +#destroy+ doesn't disassociate a model from associated ones
+    #   if there are association declared in the model class
+    #
     # @param model [Dynamoid::Document] a model
     # @return [Dynamoid::Document] self
     def destroy(model)

data/lib/dynamoid/validations.rb

@@ -31,17 +31,20 @@ module Dynamoid
     #
     # @private
     # @since 0.2.0
-    def save!
-      raise Dynamoid::Errors::DocumentNotValid, self unless valid?
+    def save!(options = {})
+      unless valid?
+        raise Dynamoid::Errors::DocumentNotValid, self
+      end
 
-      save(validate: false)
-      self
+      super
     end
 
     def update_attribute(attribute, value)
       write_attribute(attribute, value)
       save(validate: false)
       self
+    rescue Dynamoid::Errors::StaleObjectError
+      self
     end
 
     module ClassMethods

data/lib/dynamoid/version.rb

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

data/lib/dynamoid.rb

@@ -35,6 +35,7 @@ require 'dynamoid/loadable'
 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.11.0
+  version: 3.12.1
 platform: ruby
 authors:
 - Josh Symonds
@@ -21,7 +21,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-12 00:00:00.000000000 Z
+date: 2025-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -242,12 +242,15 @@ 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
@@ -261,10 +264,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: http://github.com/Dynamoid/dynamoid
-  source_code_uri: https://github.com/Dynamoid/dynamoid/tree/v3.11.0
-  changelog_uri: https://github.com/Dynamoid/dynamoid/blob/v3.11.0/CHANGELOG.md
+  source_code_uri: https://github.com/Dynamoid/dynamoid/tree/v3.12.1
+  changelog_uri: https://github.com/Dynamoid/dynamoid/blob/v3.12.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/Dynamoid/dynamoid/issues
-  documentation_uri: https://www.rubydoc.info/gems/dynamoid/3.11.0
+  documentation_uri: https://www.rubydoc.info/gems/dynamoid/3.12.1
   funding_uri: https://opencollective.com/dynamoid
   wiki_uri: https://github.com/Dynamoid/dynamoid/wiki
   rubygems_mfa_required: 'true'