dynamoid 3.2.0 → 3.6.0

data/lib/dynamoid/identity_map.rb

@@ -13,6 +13,7 @@ module Dynamoid
         @identity_map ||= {}
       end
 
+      # @private
       def from_database(attrs = {})
         return super if identity_map_off?
 
@@ -29,6 +30,7 @@ module Dynamoid
         document
       end
 
+      # @private
       def find_by_id(id, options = {})
         return super if identity_map_off?
 
@@ -41,6 +43,7 @@ module Dynamoid
         identity_map[key] || super
       end
 
+      # @private
       def identity_map_key(attrs)
         key = attrs[hash_key].to_s
         key += "::#{attrs[range_key]}" if range_key
@@ -60,6 +63,7 @@ module Dynamoid
       self.class.identity_map
     end
 
+    # @private
     def save(*args)
       return super if self.class.identity_map_off?
 
@@ -69,6 +73,7 @@ module Dynamoid
       result
     end
 
+    # @private
     def delete
       return super if self.class.identity_map_off?
 
@@ -76,6 +81,7 @@ module Dynamoid
       super
     end
 
+    # @private
     def identity_map_key
       key = hash_key.to_s
       key += "::#{range_value}" if self.class.range_key

data/lib/dynamoid/indexes.rb

@@ -15,19 +15,43 @@ module Dynamoid
       # Defines a Global Secondary index on a table. Keys can be specified as
       # hash-only, or hash & range.
       #
-      # @param [Hash] options options to pass for this table
-      # @option options [Symbol] :name the name for the index; this still gets
-      #         namespaced.  If not specified, will use a default name.
-      # @option options [Symbol] :hash_key the index hash key column.
-      # @option options [Symbol] :range_key the index range key column (if
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     field :category
+      #
+      #     global_secondary_indexes hash_key: :category
+      #   end
+      #
+      # The full example with all the options being specified:
+      #
+      #   global_secondary_indexes hash_key: :category,
+      #                            range_key: :created_at,
+      #                            name: 'posts_category_created_at_index',
+      #                            projected_attributes: :all,
+      #                            read_capacity: 100,
+      #                            write_capacity: 20
+      #
+      # Global secondary index should be declared after fields for mentioned
+      # hash key and optional range key are declared (with method +field+)
+      #
+      # The only mandatory option is +hash_key+. Raises
+      # +Dynamoid::Errors::InvalidIndex+ exception if passed incorrect
+      # options.
+      #
+      # @param [Hash] options the options to pass for this table
+      # @option options [Symbol] name the name for the index; this still gets
+      #         namespaced. If not specified, will use a default name.
+      # @option options [Symbol] hash_key the index hash key column.
+      # @option options [Symbol] range_key the index range key column (if
       #         applicable).
-      # @option options [Symbol, Array<Symbol>] :projected_attributes table
-      #         attributes to project for this index. Can be :keys_only, :all
+      # @option options [Symbol, Array<Symbol>] projected_attributes table
+      #         attributes to project for this index. Can be +:keys_only+, +:all+
       #         or an array of included fields. If not specified, defaults to
-      #         :keys_only.
-      # @option options [Integer] :read_capacity set the read capacity for the
+      #         +:keys_only+.
+      # @option options [Integer] read_capacity set the read capacity for the
       #         index; does not work on existing indexes.
-      # @option options [Integer] :write_capacity set the write capacity for
+      # @option options [Integer] write_capacity set the write capacity for
       #         the index; does not work on existing indexes.
       def global_secondary_index(options = {})
         unless options.present?
@@ -55,14 +79,38 @@ module Dynamoid
       # Defines a local secondary index on a table. Will use the same primary
       # hash key as the table.
       #
+      #   class Comment
+      #     include Dynamoid::Document
+      #
+      #     table hash_key: :post_id
+      #     range :created_at, :datetime
+      #     field :author_id
+      #
+      #     local_secondary_indexes hash_key: :author_id
+      #   end
+      #
+      # The full example with all the options being specified:
+      #
+      #   local_secondary_indexes range_key: :created_at,
+      #                           name: 'posts_created_at_index',
+      #                           projected_attributes: :all
+      #
+      # Local secondary index should be declared after fields for mentioned
+      # hash key and optional range key are declared (with method +field+) as
+      # well as after +table+ method call.
+      #
+      # The only mandatory option is +range_key+. Raises
+      # +Dynamoid::Errors::InvalidIndex+ exception if passed incorrect
+      # options.
+      #
       # @param [Hash] options options to pass for this index.
-      # @option options [Symbol] :name the name for the index; this still gets
+      # @option options [Symbol] name the name for the index; this still gets
       #         namespaced. If not specified, a name is automatically generated.
-      # @option options [Symbol] :range_key the range key column for the index.
-      # @option options [Symbol, Array<Symbol>] :projected_attributes table
-      #         attributes to project for this index. Can be :keys_only, :all
+      # @option options [Symbol] range_key the range key column for the index.
+      # @option options [Symbol, Array<Symbol>] projected_attributes table
+      #         attributes to project for this index. Can be +:keys_only+, +:all+
       #         or an array of included fields. If not specified, defaults to
-      #         :keys_only.
+      #         +:keys_only+.
       def local_secondary_index(options = {})
         unless options.present?
           raise Dynamoid::Errors::InvalidIndex, 'empty index definition'
@@ -94,6 +142,13 @@ module Dynamoid
         self
       end
 
+      # Returns an index by its hash key and optional range key.
+      #
+      # It works only for indexes without explicit name declared.
+      #
+      # @param hash [scalar] the hash key used to declare an index
+      # @param range [scalar] the range key used to declare an index (optional)
+      # @return [Dynamoid::Indexes::Index, nil] index object or nil if it isn't found
       def find_index(hash, range = nil)
         index = indexes[index_key(hash, range)]
         index
@@ -150,6 +205,10 @@ module Dynamoid
         local_secondary_indexes.merge(global_secondary_indexes)
       end
 
+      # Returns an array of hash keys for all the declared Glocal Secondary
+      # Indexes.
+      #
+      # @return [Array[String]] array of hash keys
       def indexed_hash_keys
         global_secondary_indexes.map do |_name, index|
           index.hash_key.to_s
@@ -165,8 +224,8 @@ module Dynamoid
       DEFAULT_PROJECTION_TYPE = :keys_only
 
       attr_accessor :name, :dynamoid_class, :type, :hash_key, :range_key,
-        :hash_key_schema, :range_key_schema, :projected_attributes,
-        :read_capacity, :write_capacity
+                    :hash_key_schema, :range_key_schema, :projected_attributes,
+                    :read_capacity, :write_capacity
 
       validate do
         validate_index_type

data/lib/dynamoid/loadable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module Loadable
+    extend ActiveSupport::Concern
+
+    def load(attrs)
+      attrs.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+    # Reload an object from the database -- if you suspect the object has changed in the datastore and you need those
+    # changes to be reflected immediately, you would call this method. This is a consistent read.
+    #
+    # @return [Dynamoid::Document] the document this method was called on
+    #
+    # @since 0.2.0
+    def reload
+      options = { consistent_read: true }
+
+      if self.class.range_key
+        options[:range_key] = range_value
+      end
+
+      self.attributes = self.class.find(hash_key, options).attributes
+      @associations.values.each(&:reset)
+      self
+    end
+  end
+end

data/lib/dynamoid/log/formatter.rb

@@ -0,0 +1,26 @@
+module Dynamoid
+  module Log
+    module Formatter
+
+      # https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Log/Formatter.html
+      # https://docs.aws.amazon.com/sdk-for-ruby/v2/api/Seahorse/Client/Response.html
+      # https://aws.amazon.com/ru/blogs/developer/logging-requests/
+      class Debug
+        def format(response)
+          bold = "\x1b[1m"
+          color = "\x1b[34m"
+          reset = "\x1b[0m"
+
+          [
+            response.context.operation.name,
+            "#{bold}#{color}\nRequest:\n#{reset}#{bold}",
+            JSON.pretty_generate(JSON.parse(response.context.http_request.body.string)),
+            "#{bold}#{color}\nResponse:\n#{reset}#{bold}",
+            JSON.pretty_generate(JSON.parse(response.context.http_response.body.string)),
+            reset
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/middleware/identity_map.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module Middleware
     class IdentityMap
       def initialize(app)

data/lib/dynamoid/persistence.rb

@@ -4,16 +4,22 @@ require 'bigdecimal'
 require 'securerandom'
 require 'yaml'
 
+require 'dynamoid/persistence/import'
+require 'dynamoid/persistence/update_fields'
+require 'dynamoid/persistence/upsert'
+require 'dynamoid/persistence/save'
+
 # encoding: utf-8
 module Dynamoid
-  # Persistence is responsible for dumping objects to and marshalling objects from the datastore. It tries to reserialize
-  # values to be of the same type as when they were passed in, based on the fields in the class.
+  #   # Persistence is responsible for dumping objects to and marshalling objects from the datastore. It tries to reserialize
+  #   # values to be of the same type as when they were passed in, based on the fields in the class.
   module Persistence
     extend ActiveSupport::Concern
 
     attr_accessor :new_record
     alias new_record? new_record
 
+    # @private
     UNIX_EPOCH_DATE = Date.new(1970, 1, 1).freeze
 
     module ClassMethods
@@ -23,15 +29,66 @@ module Dynamoid
         @table_name ||= [Dynamoid::Config.namespace.to_s, table_base_name].reject(&:empty?).join('_')
       end
 
-      # Creates a table.
+      # Create a table.
+      #
+      # Uses a configuration specified in a model class (with the +table+
+      # method) e.g. table name, schema (hash and range keys), global and local
+      # secondary indexes, billing mode and write/read capacity.
+      #
+      # For instance here
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     table key: :uuid
+      #     range :last_name
+      #
+      #     field :first_name
+      #     field :last_name
+      #   end
+      #
+      #   User.create_table
+      #
+      # +create_table+ method call will create a table +dynamoid_users+ with
+      # hash key +uuid+ and range key +name+, DynamoDB default billing mode and
+      # Dynamoid default read/write capacity units (100/20).
+      #
+      # All the configuration can be overridden with +options+ argument.
+      #
+      #   User.create_table(table_name: 'users', read_capacity: 200, write_capacity: 40)
+      #
+      # Dynamoid creates a table synchronously by default. DynamoDB table
+      # creation is an asynchronous operation and a client should wait until a
+      # table status changes to +ACTIVE+ and a table becomes available. That's
+      # why Dynamoid is polling a table status and returns results only when a
+      # table becomes available.
+      #
+      # Polling is configured with +Dynamoid::Config.sync_retry_max_times+ and
+      # +Dynamoid::Config.sync_retry_wait_seconds+ configuration options. If
+      # table creation takes more time than configured waiting time then
+      # Dynamoid stops polling and returns +true+.
       #
-      # @param [Hash] options options to pass for table creation
-      # @option options [Symbol] :id the id field for the table
-      # @option options [Symbol] :table_name the actual name for the table
-      # @option options [Integer] :read_capacity set the read capacity for the table; does not work on existing tables
-      # @option options [Integer] :write_capacity set the write capacity for the table; does not work on existing tables
-      # @option options [Hash] {range_key => :type} a hash of the name of the range key and a symbol of its type
-      # @option options [Symbol] :hash_key_type the dynamo type of the hash key (:string or :number)
+      # In order to return back asynchronous behaviour and not to wait until a
+      # table is created the +sync: false+ option should be specified.
+      #
+      #   User.create_table(sync: false)
+      #
+      # Subsequent method calls for the same table will be ignored.
+      #
+      # @param options [Hash]
+      #
+      # @option options [Symbol] :table_name name of the table
+      # @option options [Symbol] :id hash key name of the table
+      # @option options [Symbol] :hash_key_type Dynamoid type of the hash key - +:string+, +:integer+ or any other scalar type
+      # @option options [Hash] :range_key a Hash with range key name and type in format +{ <name> => <type> }+ e.g. +{ last_name: :string }+
+      # @option options [String] :billing_mode billing mode of a table - either +PROVISIONED+ (default) or +PAY_PER_REQUEST+ (for On-Demand Mode)
+      # @option options [Integer] :read_capacity read capacity units for the table; does not work on existing tables and is ignored when billing mode is +PAY_PER_REQUEST+
+      # @option options [Integer] :write_capacity write capacity units for the table; does not work on existing tables and is ignored when billing mode is +PAY_PER_REQUEST+
+      # @option options [Hash] :local_secondary_indexes
+      # @option options [Hash] :global_secondary_indexes
+      # @option options [true|false] :sync specifies should the method call be synchronous and wait until a table is completely created
+      #
+      # @return [true|false] Whether a table created successfully
       # @since 0.4.0
       def create_table(options = {})
         range_key_hash = if range_key
@@ -41,6 +98,7 @@ module Dynamoid
         options = {
           id: hash_key,
           table_name: table_name,
+          billing_mode: capacity_mode,
           write_capacity: write_capacity,
           read_capacity: read_capacity,
           range_key: range_key_hash,
@@ -49,77 +107,297 @@ module Dynamoid
           global_secondary_indexes: global_secondary_indexes.values
         }.merge(options)
 
-        Dynamoid.adapter.create_table(options[:table_name], options[:id], options)
+        created_successfuly = Dynamoid.adapter.create_table(options[:table_name], options[:id], options)
+
+        if created_successfuly && self.options[:expires]
+          attribute = self.options[:expires][:field]
+          Dynamoid.adapter.update_time_to_live(table_name: table_name, attribute: attribute)
+        end
       end
 
-      # Deletes the table for the model
+      # Deletes the table for the model.
+      #
+      # Dynamoid deletes a table asynchronously and doesn't wait until a table
+      # is deleted completely.
+      #
+      # Subsequent method calls for the same table will be ignored.
       def delete_table
         Dynamoid.adapter.delete_table(table_name)
       end
 
+      # @private
       def from_database(attrs = {})
-        clazz = choose_right_class(attrs)
-        attrs_undumped = Undumping.undump_attributes(attrs, clazz.attributes)
-        clazz.new(attrs_undumped).tap { |r| r.new_record = false }
+        klass = choose_right_class(attrs)
+        attrs_undumped = Undumping.undump_attributes(attrs, klass.attributes)
+        klass.new(attrs_undumped).tap { |r| r.new_record = false }
       end
 
-      # Creates several models at once.
-      # Neither callbacks nor validations run.
-      # It works efficiently because of using BatchWriteItem.
+      # Create several models at once.
       #
-      # Returns array of models
+      #   users = User.import([{ name: 'a' }, { name: 'b' }])
       #
-      # Uses backoff specified by `Dynamoid::Config.backoff` config option
+      # +import+ is a relatively low-level method and bypasses some
+      # mechanisms like callbacks and validation.
       #
-      # @param [Array<Hash>] items
+      # It sets timestamp fields +created_at+ and +updated_at+ if they are
+      # blank. It sets a hash key field as well if it's blank. It expects that
+      # the hash key field is +string+ and sets a random UUID value if the field
+      # value is blank. All the field values are type casted to the declared
+      # types.
       #
-      # @example
-      #   User.import([{ name: 'a' }, { name: 'b' }])
-      def import(objects)
-        documents = objects.map do |attrs|
-          attrs = attrs.symbolize_keys
+      # It works efficiently and uses the `BatchWriteItem` operation. In order
+      # to cope with throttling it uses a backoff strategy if it's specified with
+      # `Dynamoid::Config.backoff` configuration option.
+      #
+      # Because of the nature of DynamoDB and its limits only 25 models can be
+      # saved at once. So multiple HTTP requests can be sent to DynamoDB.
+      #
+      # @param array_of_attributes [Array<Hash>]
+      # @return [Array] Created models
+      def import(array_of_attributes)
+        Import.call(self, array_of_attributes)
+      end
 
-          if Dynamoid::Config.timestamps
-            time_now = DateTime.now.in_time_zone(Time.zone)
-            attrs[:created_at] ||= time_now
-            attrs[:updated_at] ||= time_now
-          end
+      # Create a model.
+      #
+      # Initializes a new model and immediately saves it to DynamoDB.
+      #
+      #   User.create(first_name: 'Mark', last_name: 'Tyler')
+      #
+      # Accepts both Hash and Array of Hashes and can create several models.
+      #
+      #   User.create([{ first_name: 'Alice' }, { first_name: 'Bob' }])
+      #
+      # Creates a model and pass it into a block to set other attributes.
+      #
+      #   User.create(first_name: 'Mark') do |u|
+      #     u.age = 21
+      #   end
+      #
+      # Validates model and runs callbacks.
+      #
+      # @param attrs [Hash|Array[Hash]] Attributes of the models
+      # @param block [Proc] Block to process a document after initialization
+      # @return [Dynamoid::Document] The created document
+      # @since 0.2.0
+      def create(attrs = {}, &block)
+        if attrs.is_a?(Array)
+          attrs.map { |attr| create(attr, &block) }
+        else
+          build(attrs, &block).tap(&:save)
+        end
+      end
 
-          build(attrs).tap do |item|
-            item.hash_key = SecureRandom.uuid if item.hash_key.blank?
-          end
+      # Create a model.
+      #
+      # Initializes a new object and immediately saves it to the Dynamoid.
+      # Raises an exception +Dynamoid::Errors::DocumentNotValid+ if validation
+      # failed. Accepts both Hash and Array of Hashes and can create several
+      # models.
+      #
+      # @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
+      # @since 0.2.0
+      def create!(attrs = {}, &block)
+        if attrs.is_a?(Array)
+          attrs.map { |attr| create!(attr, &block) }
+        else
+          build(attrs, &block).tap(&:save!)
         end
+      end
 
-        if Dynamoid.config.backoff
-          backoff = nil
+      # Update document with provided attributes.
+      #
+      # Instantiates document and saves changes. Runs validations and
+      # callbacks. Don't save changes if validation fails.
+      #
+      #   User.update('1', age: 26)
+      #
+      # If range key is declared for a model it should be passed as well:
+      #
+      #   User.update('1', 'Tylor', age: 26)
+      #
+      # @param hash_key [Scalar value] hash key
+      # @param range_key_value [Scalar value] range key (optional)
+      # @param attrs [Hash]
+      # @return [Dynamoid::Document] Updated document
+      def update(hash_key, range_key_value = nil, attrs)
+        model = find(hash_key, range_key: range_key_value, consistent_read: true)
+        model.update_attributes(attrs)
+        model
+      end
 
-          array = documents.map do |d|
-            Dumping.dump_attributes(d.attributes, attributes)
-          end
+      # Update document with provided attributes.
+      #
+      # Instantiates document and saves changes. Runs validations and
+      # callbacks.
+      #
+      #   User.update!('1', age: 26)
+      #
+      # If range key is declared for a model it should be passed as well:
+      #
+      #   User.update('1', 'Tylor', age: 26)
+      #
+      # Raises +Dynamoid::Errors::DocumentNotValid+ exception if validation fails.
+      #
+      # @param hash_key [Scalar value] hash key
+      # @param range_key_value [Scalar value] range key (optional)
+      # @param attrs [Hash]
+      # @return [Dynamoid::Document] Updated document
+      def update!(hash_key, range_key_value = nil, attrs)
+        model = find(hash_key, range_key: range_key_value, consistent_read: true)
+        model.update_attributes!(attrs)
+        model
+      end
 
-          Dynamoid.adapter.batch_write_item(table_name, array) do |has_unprocessed_items|
-            if has_unprocessed_items
-              backoff ||= Dynamoid.config.build_backoff
-              backoff.call
-            else
-              backoff = nil
-            end
-          end
+      # Update document.
+      #
+      # Doesn't run validations and callbacks.
+      #
+      #   User.update_fields('1', age: 26)
+      #
+      # If range key is declared for a model it should be passed as well:
+      #
+      #   User.update_fields('1', 'Tylor', age: 26)
+      #
+      # Can make a conditional update so a document will be updated only if it
+      # meets the specified conditions. Conditions can be specified as a +Hash+
+      # with +:if+ key:
+      #
+      #   User.update_fields('1', { age: 26 }, if: { version: 1 })
+      #
+      # Here +User+ model has an integer +version+ field and the document will
+      # be updated only if the +version+ attribute currently has value 1.
+      #
+      # If a document with specified hash and range keys doesn't exist or
+      # conditions were specified and failed the method call returns +nil+.
+      #
+      # +update_fields+ uses the +UpdateItem+ operation so it saves changes and
+      # loads an updated document back with one HTTP request.
+      #
+      # @param hash_key_value [Scalar value] hash key
+      # @param range_key_value [Scalar value] range key (optional)
+      # @param attrs [Hash]
+      # @param conditions [Hash] (optional)
+      # @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
+        if optional_params.first.is_a?(Hash)
+          range_key_value = nil
+          attrs, conditions = optional_params[0..1]
         else
-          array = documents.map do |d|
-            Dumping.dump_attributes(d.attributes, attributes)
-          end
+          range_key_value = optional_params.first
+          attrs, conditions = optional_params[1..2]
+        end
+
+        UpdateFields.call(self,
+                          partition_key: hash_key_value,
+                          sort_key: range_key_value,
+                          attributes: attrs,
+                          conditions: conditions)
+      end
 
-          Dynamoid.adapter.batch_write_item(table_name, array)
+      # Update an existing document or create a new one.
+      #
+      # If a document with specified hash and range keys doesn't exist it
+      # creates a new document with specified attributes. Doesn't run
+      # validations and callbacks.
+      #
+      #   User.upsert('1', age: 26)
+      #
+      # If range key is declared for a model it should be passed as well:
+      #
+      #   User.upsert('1', 'Tylor', age: 26)
+      #
+      # Can make a conditional update so a document will be updated only if it
+      # meets the specified conditions. Conditions can be specified as a +Hash+
+      # with +:if+ key:
+      #
+      #   User.upsert('1', { age: 26 }, if: { version: 1 })
+      #
+      # Here +User+ model has an integer +version+ field and the document will
+      # be updated only if the +version+ attribute currently has value 1.
+      #
+      # If conditions were specified and failed the method call returns +nil+.
+      #
+      # +upsert+ uses the +UpdateItem+ operation so it saves changes and loads
+      # an updated document back with one HTTP request.
+      #
+      # @param hash_key_value [Scalar value] hash key
+      # @param range_key_value [Scalar value] range key (optional)
+      # @param attrs [Hash]
+      # @param conditions [Hash] (optional)
+      # @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
+        if optional_params.first.is_a?(Hash)
+          range_key_value = nil
+          attrs, conditions = optional_params[0..1]
+        else
+          range_key_value = optional_params.first
+          attrs, conditions = optional_params[1..2]
         end
 
-        documents.each { |d| d.new_record = false }
-        documents
+        Upsert.call(self,
+                    partition_key: hash_key_value,
+                    sort_key: range_key_value,
+                    attributes: attrs,
+                    conditions: conditions)
+      end
+
+      # Increase a numeric field by specified value.
+      #
+      #   User.inc('1', age: 2)
+      #
+      # Can update several fields at once.
+      #
+      #   User.inc('1', age: 2, version: 1)
+      #
+      # If range key is declared for a model it should be passed as well:
+      #
+      #   User.inc('1', 'Tylor', age: 2)
+      #
+      # Uses efficient low-level +UpdateItem+ operation and does only one HTTP
+      # request.
+      #
+      # Doesn't run validations and callbacks. Doesn't update +created_at+ and
+      # +updated_at+ as well.
+      #
+      # @param hash_key_value [Scalar value] hash key
+      # @param range_key_value [Scalar value] range key (optional)
+      # @param counters [Hash] value to increase by
+      def inc(hash_key_value, range_key_value = nil, counters)
+        options = if range_key
+                    value_casted = TypeCasting.cast_field(range_key_value, attributes[range_key])
+                    value_dumped = Dumping.dump_field(value_casted, attributes[range_key])
+                    { range_key: value_dumped }
+                  else
+                    {}
+                  end
+
+        Dynamoid.adapter.update_item(table_name, hash_key_value, options) do |t|
+          counters.each do |k, v|
+            value_casted = TypeCasting.cast_field(v, attributes[k])
+            value_dumped = Dumping.dump_field(value_casted, attributes[k])
+
+            t.add(k => value_dumped)
+          end
+        end
       end
     end
 
-    # Set updated_at and any passed in field to current DateTime. Useful for things like last_login_at, etc.
+    # Update document timestamps.
     #
+    # Set +updated_at+ attribute to current DateTime.
+    #
+    #   post.touch
+    #
+    # Can update another field in addition with the same timestamp if it's name passed as argument.
+    #
+    #   user.touch(:last_login_at)
+    #
+    # @param name [Symbol] attribute name to update (optional)
     def touch(name = nil)
       now = DateTime.now
       self.updated_at = now
@@ -127,43 +405,109 @@ module Dynamoid
       save
     end
 
-    # Is this object persisted in the datastore? Required for some ActiveModel integration stuff.
+    # Is this object persisted in DynamoDB?
+    #
+    #   user = User.new
+    #   user.persisted? # => false
+    #
+    #   user.save
+    #   user.persisted? # => true
     #
+    # @return [true|false]
     # @since 0.2.0
     def persisted?
-      !new_record?
+      !(new_record? || @destroyed)
     end
 
-    # Run the callbacks and then persist this object in the datastore.
+    # Create new model or persist changes.
+    #
+    # Run the validation and callbacks. Returns +true+ if saving is successful
+    # and +false+ otherwise.
+    #
+    #   user = User.new
+    #   user.save # => true
+    #
+    #   user.age = 26
+    #   user.save # => true
+    #
+    # Validation can be skipped with +validate: false+ option:
+    #
+    #   user = User.new(age: -1)
+    #   user.save(validate: false) # => true
+    #
+    # +save+ by default sets timestamps attributes - +created_at+ and
+    # +updated_at+ when creates new model and updates +updated_at+ attribute
+    # when update 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.
+    #
+    # 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
     # @since 0.2.0
-    def save(_options = {})
-      self.class.create_table
+    def save(options = {})
+      self.class.create_table(sync: true)
 
-      if new_record?
-        conditions = { unless_exists: [self.class.hash_key] }
-        conditions[:unless_exists] << range_key if range_key
+      @_touch_record = options[:touch]
 
-        run_callbacks(:create) { persist(conditions) }
+      if new_record?
+        run_callbacks(:create) do
+          run_callbacks(:save) do
+            Save.call(self)
+          end
+        end
       else
-        persist
+        run_callbacks(:save) do
+          Save.call(self)
+        end
       end
     end
 
-    # Updates multiple attributes at once, saving the object once the updates are complete.
+    # Update multiple attributes at once, saving the object once the updates
+    # are complete. Returns +true+ if saving is successful and +false+
+    # otherwise.
     #
-    # @param [Hash] attributes a hash of attributes to update
+    #   user.update_attributes(age: 27, last_name: 'Tylor')
     #
+    # @param attributes [Hash] a hash of attributes to update
+    # @return [true|false] Whether updating successful or not
     # @since 0.2.0
     def update_attributes(attributes)
       attributes.each { |attribute, value| write_attribute(attribute, value) }
       save
     end
 
-    # Updates multiple attributes at once, saving the object once the updates are complete.
-    # Raises a Dynamoid::Errors::DocumentNotValid exception if there is vaidation and it fails.
+    # Update multiple attributes at once, saving the object once the updates
+    # are complete.
     #
-    # @param [Hash] attributes a hash of attributes to update
+    #   user.update_attributes!(age: 27, last_name: 'Tylor')
+    #
+    # Raises a +Dynamoid::Errors::DocumentNotValid+ exception if some vaidation
+    # fails.
+    #
+    # @param attributes [Hash] a hash of attributes to update
     def update_attributes!(attributes)
       attributes.each { |attribute, value| write_attribute(attribute, value) }
       save!
@@ -171,20 +515,68 @@ module Dynamoid
 
     # Update a single attribute, saving the object afterwards.
     #
-    # @param [Symbol] attribute the attribute to update
-    # @param [Object] value the value to assign it
+    # Returns +true+ if saving is successful and +false+ otherwise.
+    #
+    #   user.update_attribute(:last_name, 'Tylor')
     #
+    # @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)
       write_attribute(attribute, value)
       save
     end
 
+    # Update a model.
+    #
+    # Runs validation and callbacks. Reloads all attribute values.
+    #
+    # Accepts mandatory block in order to specify operations which will modify
+    # 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+).
+    #
+    #   user.update do |t|
+    #     t.add(age: 1, followers_count: 5)
+    #     t.add(hobbies: ['skying', 'climbing'])
+    #   end
+    #
+    # Operation +delete+ is applied to collection attribute types and
+    # substructs one collection from another.
+    #
+    #   user.update do |t|
+    #     t.delete(hobbies: ['skying'])
+    #   end
+    #
+    # Operation +set+ just changes an attribute value:
+    #
+    #   user.update do |t|
+    #     t.set(age: 21)
+    #   end
+    #
+    # All the operations works like +ADD+, +DELETE+ and +PUT+ actions supported
+    # by +AttributeUpdates+
+    # {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html]
+    # of +UpdateItem+ operation.
     #
-    # update!() will increment the lock_version if the table has the column, but will not check it. Thus, a concurrent save will
-    # never cause an update! to fail, but an update! may cause a concurrent save to fail.
+    # Can update a model conditionaly:
     #
+    #   user.update(if: { age: 20 }) do |t|
+    #     t.add(age: 1)
+    #   end
     #
+    # If a document doesn't meet conditions it raises
+    # +Dynamoid::Errors::StaleObjectError+ exception.
+    #
+    # It will increment the +lock_version+ attribute if a table has the column,
+    # but will not check it. Thus, a concurrent +save+ call will never cause an
+    # +update!+ to fail, but an +update!+ may cause a concurrent +save+ to
+    # fail.
+    #
+    # @param conditions [Hash] Conditions on model attributes to make a conditional update (optional)
     def update!(conditions = {})
       run_callbacks(:update) do
         options = range_key ? { range_key: Dumping.dump_field(read_attribute(range_key), self.class.attributes[range_key]) } : {}
@@ -208,6 +600,54 @@ module Dynamoid
       end
     end
 
+    # Update a model.
+    #
+    # Runs validation and callbacks. Reloads all attribute values.
+    #
+    # Accepts mandatory block in order to specify operations which will modify
+    # 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+).
+    #
+    #   user.update do |t|
+    #     t.add(age: 1, followers_count: 5)
+    #     t.add(hobbies: ['skying', 'climbing'])
+    #   end
+    #
+    # Operation +delete+ is applied to collection attribute types and
+    # substructs one collection from another.
+    #
+    #   user.update do |t|
+    #     t.delete(hobbies: ['skying'])
+    #   end
+    #
+    # Operation +set+ just changes an attribute value:
+    #
+    #   user.update do |t|
+    #     t.set(age: 21)
+    #   end
+    #
+    # All the operations works like +ADD+, +DELETE+ and +PUT+ actions supported
+    # by +AttributeUpdates+
+    # {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html]
+    # of +UpdateItem+ operation.
+    #
+    # Can update a model conditionaly:
+    #
+    #   user.update(if: { age: 20 }) do |t|
+    #     t.add(age: 1)
+    #   end
+    #
+    # If a document doesn't meet conditions it just returns +false+. Otherwise it returns +true+.
+    #
+    # It will increment the +lock_version+ attribute if a table has the column,
+    # but will not check it. Thus, a concurrent +save+ call will never cause an
+    # +update!+ to fail, but an +update!+ may cause a concurrent +save+ to
+    # fail.
+    #
+    # @param conditions [Hash] Conditions on model attributes to make a conditional update (optional)
     def update(conditions = {}, &block)
       update!(conditions, &block)
       true
@@ -215,51 +655,117 @@ module Dynamoid
       false
     end
 
-    # Initializes attribute to zero if nil and adds the value passed as by (default is 1).
-    # Only makes sense for number-based attributes. Returns self.
+    # Change numeric attribute value.
+    #
+    # Initializes attribute to zero if +nil+ and adds the specified value (by
+    # default is 1). Only makes sense for number-based attributes.
+    #
+    #   user.increment(:followers_count)
+    #   user.increment(:followers_count, 2)
+    #
+    # @param attribute [Symbol] attribute name
+    # @param by [Numeric] value to add (optional)
+    # @return [Dynamoid::Document] self
     def increment(attribute, by = 1)
       self[attribute] ||= 0
       self[attribute] += by
       self
     end
 
-    # Wrapper around increment that saves the record.
-    # Returns true if the record could be saved.
+    # Change numeric attribute value and save a model.
+    #
+    # Initializes attribute to zero if +nil+ and adds the specified value (by
+    # default is 1). Only makes sense for number-based attributes.
+    #
+    #   user.increment!(:followers_count)
+    #   user.increment!(:followers_count, 2)
+    #
+    # Returns +true+ if a model was saved and +false+ otherwise.
+    #
+    # @param attribute [Symbol] attribute name
+    # @param by [Numeric] value to add (optional)
+    # @return [true|false] whether saved model successfully
     def increment!(attribute, by = 1)
       increment(attribute, by)
       save
     end
 
-    # Initializes attribute to zero if nil and subtracts the value passed as by (default is 1).
-    # Only makes sense for number-based attributes. Returns self.
+    # Change numeric attribute value.
+    #
+    # Initializes attribute to zero if +nil+ and subtracts the specified value
+    # (by default is 1). Only makes sense for number-based attributes.
+    #
+    #   user.decrement(:followers_count)
+    #   user.decrement(:followers_count, 2)
+    #
+    # @param attribute [Symbol] attribute name
+    # @param by [Numeric] value to subtract (optional)
+    # @return [Dynamoid::Document] self
     def decrement(attribute, by = 1)
       self[attribute] ||= 0
       self[attribute] -= by
       self
     end
 
-    # Wrapper around decrement that saves the record.
-    # Returns true if the record could be saved.
+    # Change numeric attribute value and save a model.
+    #
+    # Initializes attribute to zero if +nil+ and subtracts the specified value
+    # (by default is 1). Only makes sense for number-based attributes.
+    #
+    #   user.decrement!(:followers_count)
+    #   user.decrement!(:followers_count, 2)
+    #
+    # Returns +true+ if a model was saved and +false+ otherwise.
+    #
+    # @param attribute [Symbol] attribute name
+    # @param by [Numeric] value to subtract (optional)
+    # @return [true|false] whether saved model successfully
     def decrement!(attribute, by = 1)
       decrement(attribute, by)
       save
     end
 
-    # Delete this object, but only after running callbacks for it.
+    # Delete a model.
+    #
+    # Runs callbacks.
+    #
+    # Supports optimistic locking with the +lock_version+ attribute and doesn't
+    # delete a model if it's already changed.
     #
+    # Returns +true+ if deleted successfully and +false+ otherwise.
+    #
+    # @return [true|false] whether deleted successfully
     # @since 0.2.0
     def destroy
       ret = run_callbacks(:destroy) do
         delete
       end
+
+      @destroyed = true
+
       ret == false ? false : self
     end
 
+    # Delete a model.
+    #
+    # Runs callbacks.
+    #
+    # Supports optimistic locking with the +lock_version+ attribute and doesn't
+    # delete a model if it's already changed.
+    #
+    # Raises +Dynamoid::Errors::RecordNotDestroyed+ exception if model deleting
+    # failed.
     def destroy!
       destroy || (raise Dynamoid::Errors::RecordNotDestroyed, self)
     end
 
-    # Delete this object from the datastore.
+    # Delete a model.
+    #
+    # Supports optimistic locking with the +lock_version+ attribute and doesn't
+    # delete a model if it's already changed.
+    #
+    # Raises +Dynamoid::Errors::StaleObjectError+ exception if cannot delete a
+    # model.
     #
     # @since 0.2.0
     def delete
@@ -276,48 +782,12 @@ module Dynamoid
           end
         options[:conditions] = conditions
       end
+
+      @destroyed = true
+
       Dynamoid.adapter.delete(self.class.table_name, hash_key, options)
     rescue Dynamoid::Errors::ConditionalCheckFailedException
       raise Dynamoid::Errors::StaleObjectError.new(self, 'delete')
     end
-
-    private
-
-    # Persist the object into the datastore. Assign it an id first if it doesn't have one.
-    #
-    # @since 0.2.0
-    def persist(conditions = nil)
-      run_callbacks(:save) do
-        self.hash_key = SecureRandom.uuid if hash_key.blank?
-
-        # Add an exists check to prevent overwriting existing records with new ones
-        if new_record?
-          conditions ||= {}
-          (conditions[:unless_exists] ||= []) << self.class.hash_key
-        end
-
-        # Add an optimistic locking check if the lock_version column exists
-        if self.class.attributes[:lock_version]
-          conditions ||= {}
-          self.lock_version = (lock_version || 0) + 1
-          # Uses the original lock_version value from ActiveModel::Dirty in case user changed lock_version manually
-          (conditions[:if] ||= {})[:lock_version] = changes[:lock_version][0] if changes[:lock_version][0]
-        end
-
-        attributes_dumped = Dumping.dump_attributes(attributes, self.class.attributes)
-
-        begin
-          Dynamoid.adapter.write(self.class.table_name, attributes_dumped, conditions)
-          @new_record = false
-          true
-        rescue Dynamoid::Errors::ConditionalCheckFailedException => e
-          if new_record?
-            raise Dynamoid::Errors::RecordNotUnique.new(e, self)
-          else
-            raise Dynamoid::Errors::StaleObjectError.new(self, 'persist')
-          end
-        end
-      end
-    end
   end
 end