dynamoid 3.5.0 → 3.6.0

data/lib/dynamoid/criteria/ignored_conditions_detector.rb

@@ -2,6 +2,7 @@
 
 module Dynamoid
   module Criteria
+    # @private
     class IgnoredConditionsDetector
       def initialize(conditions)
         @conditions = conditions

data/lib/dynamoid/criteria/key_fields_detector.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   module Criteria
+    # @private
     class KeyFieldsDetector
       class Query
         def initialize(query_hash)
@@ -10,6 +11,10 @@ module Dynamoid #:nodoc:
           @fields = query_hash.keys.map(&:to_s).map { |s| s.split('.').first }
         end
 
+        def contain_only?(field_names)
+          (@fields - field_names.map(&:to_s)).blank?
+        end
+
         def contain?(field_name)
           @fields.include?(field_name.to_s)
         end
@@ -26,6 +31,10 @@ module Dynamoid #:nodoc:
         @result = find_keys_in_query
       end
 
+      def non_key_present?
+        !@query.contain_only?([hash_key, range_key].compact)
+      end
+
       def key_present?
         @result.present?
       end

data/lib/dynamoid/criteria/nonexistent_fields_detector.rb

@@ -2,6 +2,7 @@
 
 module Dynamoid
   module Criteria
+    # @private
     class NonexistentFieldsDetector
       def initialize(conditions, source)
         @conditions = conditions

data/lib/dynamoid/criteria/overwritten_conditions_detector.rb

@@ -2,6 +2,7 @@
 
 module Dynamoid
   module Criteria
+    # @private
     class OverwrittenConditionsDetector
       def initialize(conditions, conditions_new)
         @conditions = conditions

data/lib/dynamoid/dirty.rb

@@ -22,6 +22,7 @@ module Dynamoid
       attribute_method_affix prefix: 'restore_', suffix: '!'
     end
 
+    # @private
     module ClassMethods
       def update_fields(*)
         if model = super
@@ -44,6 +45,7 @@ module Dynamoid
       end
     end
 
+    # @private
     def save(*)
       if status = super
         changes_applied
@@ -51,24 +53,28 @@ module Dynamoid
       status
     end
 
+    # @private
     def save!(*)
       super.tap do
         changes_applied
       end
     end
 
+    # @private
     def update(*)
       super.tap do
         clear_changes_information
       end
     end
 
+    # @private
     def update!(*)
       super.tap do
         clear_changes_information
       end
     end
 
+    # @private
     def reload(*)
       super.tap do
         clear_changes_information
@@ -78,17 +84,22 @@ module Dynamoid
     # Returns +true+ if any attribute have unsaved changes, +false+ otherwise.
     #
     #   person.changed? # => false
-    #   person.name = 'bob'
+    #   person.name = 'Bob'
     #   person.changed? # => true
+    #
+    # @return [true|false]
     def changed?
       changed_attributes.present?
     end
 
-    # Returns an array with the name of the attributes with unsaved changes.
+    # Returns an array with names of the attributes with unsaved changes.
     #
+    #   person = Person.new
     #   person.changed # => []
-    #   person.name = 'bob'
+    #   person.name = 'Bob'
     #   person.changed # => ["name"]
+    #
+    # @return [Array[String]]
     def changed
       changed_attributes.keys
     end
@@ -97,18 +108,22 @@ module Dynamoid
     # and new values like <tt>attr => [original value, new value]</tt>.
     #
     #   person.changes # => {}
-    #   person.name = 'bob'
-    #   person.changes # => { "name" => ["bill", "bob"] }
+    #   person.name = 'Bob'
+    #   person.changes # => { "name" => ["Bill", "Bob"] }
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess]
     def changes
       ActiveSupport::HashWithIndifferentAccess[changed.map { |attr| [attr, attribute_change(attr)] }]
     end
 
     # Returns a hash of attributes that were changed before the model was saved.
     #
-    #   person.name # => "bob"
-    #   person.name = 'robert'
+    #   person.name # => "Bob"
+    #   person.name = 'Robert'
     #   person.save
-    #   person.previous_changes # => {"name" => ["bob", "robert"]}
+    #   person.previous_changes # => {"name" => ["Bob", "Robert"]}
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess]
     def previous_changes
       @previously_changed ||= ActiveSupport::HashWithIndifferentAccess.new
     end
@@ -116,15 +131,28 @@ module Dynamoid
     # Returns a hash of the attributes with unsaved changes indicating their original
     # values like <tt>attr => original value</tt>.
     #
-    #   person.name # => "bob"
-    #   person.name = 'robert'
-    #   person.changed_attributes # => {"name" => "bob"}
+    #   person.name # => "Bob"
+    #   person.name = 'Robert'
+    #   person.changed_attributes # => {"name" => "Bob"}
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess]
     def changed_attributes
       @changed_attributes ||= ActiveSupport::HashWithIndifferentAccess.new
     end
 
     # Handle <tt>*_changed?</tt> for +method_missing+.
-    def attribute_changed?(attr, options = {}) #:nodoc:
+    #
+    #  person.attribute_changed?(:name) # => true
+    #  person.attribute_changed?(:name, from: 'Alice')
+    #  person.attribute_changed?(:name, to: 'Bob')
+    #  person.attribute_changed?(:name, from: 'Alice', to: 'Bod')
+    #
+    # @private
+    # @param attr [Symbol] attribute name
+    # @param options [Hash] conditions on +from+ and +to+ value (optional)
+    # @option options [Symbol] :from previous attribute value
+    # @option options [Symbol] :to current attribute value
+    def attribute_changed?(attr, options = {})
       result = changes_include?(attr)
       result &&= options[:to] == __send__(attr) if options.key?(:to)
       result &&= options[:from] == changed_attributes[attr] if options.key?(:from)
@@ -132,21 +160,48 @@ module Dynamoid
     end
 
     # Handle <tt>*_was</tt> for +method_missing+.
-    def attribute_was(attr) # :nodoc:
+    #
+    #  person = Person.create(name: 'Alice')
+    #  person.name = 'Bob'
+    #  person.attribute_was(:name) # => "Alice"
+    #
+    # @private
+    # @param attr [Symbol] attribute name
+    def attribute_was(attr)
       attribute_changed?(attr) ? changed_attributes[attr] : __send__(attr)
     end
 
     # Restore all previous data of the provided attributes.
+    #
+    # @param attributes [Array[Symbol]] a list of attribute names
     def restore_attributes(attributes = changed)
       attributes.each { |attr| restore_attribute! attr }
     end
 
     # Handles <tt>*_previously_changed?</tt> for +method_missing+.
-    def attribute_previously_changed?(attr) #:nodoc:
+    #
+    #  person = Person.create(name: 'Alice')
+    #  person.name = 'Bob'
+    #  person.save
+    #  person.attribute_changed?(:name) # => true
+    #
+    # @private
+    # @param attr [Symbol] attribute name
+    # @return [true|false]
+    def attribute_previously_changed?(attr)
       previous_changes_include?(attr)
     end
 
     # Handles <tt>*_previous_change</tt> for +method_missing+.
+    #
+    #  person = Person.create(name: 'Alice')
+    #  person.name = 'Bob'
+    #  person.save
+    #  person.attribute_previously_changed(:name) # => ["Alice", "Bob"]
+    #
+    # @private
+    # @param attr [Symbol]
+    # @return [Array]
     def attribute_previous_change(attr)
       previous_changes[attr] if attribute_previously_changed?(attr)
     end
@@ -204,7 +259,7 @@ module Dynamoid
 
     # This is necessary because `changed_attributes` might be overridden in
     # other implemntations (e.g. in `ActiveRecord`)
-    alias attributes_changed_by_setter changed_attributes # :nodoc:
+    alias attributes_changed_by_setter changed_attributes
 
     # Force an attribute to have a particular "before" value
     def set_attribute_was(attr, old_value)
@@ -212,7 +267,7 @@ module Dynamoid
     end
 
     # Remove changes information for the provided attributes.
-    def clear_attribute_changes(attributes) # :doc:
+    def clear_attribute_changes(attributes)
       attributes_changed_by_setter.except!(*attributes)
     end
   end

data/lib/dynamoid/document.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # This is the base module for all domain objects that need to be persisted to
   # the database as documents.
   module Document
@@ -17,28 +17,19 @@ module Dynamoid #:nodoc:
     end
 
     module ClassMethods
-      # Set up table options, including naming it whatever you want, setting the id key, and manually overriding read and
-      # write capacity.
-      #
-      # @param [Hash] options options to pass for this table
-      # @option options [Symbol] :name the name for the table; this still gets namespaced
-      # @option options [Symbol] :id id column 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
-      #
-      # @since 0.4.0
+      # @private
       def table(options = {})
         self.options = options
         super if defined? super
       end
 
       def attr_readonly(*read_only_attributes)
-        ActiveSupport::Deprecation.warn('[Dynamoid] .attr_readonly is deprecated! Call .find instead of')
         self.read_only_attributes.concat read_only_attributes.map(&:to_s)
       end
 
-      # Returns the read_capacity for this table.
+      # Returns the read capacity for this table.
       #
+      # @return [Integer] read capacity units
       # @since 0.4.0
       def read_capacity
         options[:read_capacity] || Dynamoid::Config.read_capacity
@@ -46,31 +37,53 @@ module Dynamoid #:nodoc:
 
       # Returns the write_capacity for this table.
       #
+      # @return [Integer] write capacity units
       # @since 0.4.0
       def write_capacity
         options[:write_capacity] || Dynamoid::Config.write_capacity
       end
 
       # Returns the billing (capacity) mode for this table.
-      # Could be either :provisioned or :on_demand
+      #
+      # Could be either +provisioned+ or +on_demand+.
+      #
+      # @return [Symbol]
       def capacity_mode
         options[:capacity_mode] || Dynamoid::Config.capacity_mode
       end
 
       # Returns the field name used to support STI for this table.
+      #
+      # Default field name is +type+ but it can be overrided in the +table+
+      # method call.
+      #
+      #   User.inheritance_field # => :type
       def inheritance_field
         options[:inheritance_field] || :type
       end
 
-      # Returns the id field for this class.
+      # Returns the hash key field name for this class.
+      #
+      # By default +id+ field is used. But it can be overriden in the +table+
+      # method call.
       #
+      #   User.hash_key # => :id
+      #
+      # @return [Symbol] a hash key name
       # @since 0.4.0
       def hash_key
         options[:key] || :id
       end
 
-      # Returns the number of items for this class.
+      # Return the count of items for this class.
+      #
+      # It returns aproximate value based on DynamoDB statistic. DynamoDB
+      # updates it periodicaly so the value can be no accurate.
       #
+      # It's a reletivly cheap operation and doesn't read all the items in a
+      # table. It makes just one HTTP request to DynamoDB.
+      #
+      # @return [Integer] items count in a table
       # @since 0.6.1
       def count
         Dynamoid.adapter.count(table_name)
@@ -78,35 +91,67 @@ module Dynamoid #:nodoc:
 
       # Initialize a new object.
       #
-      # @param [Hash] attrs Attributes with which to create the object.
+      #   User.build(name: 'A')
       #
-      # @return [Dynamoid::Document] the new document
+      # Initialize an object and pass it into a block to set other attributes.
+      #
+      #   User.build(name: 'A') do |u|
+      #     u.age = 21
+      #   end
+      #
+      # The only difference between +build+ and +new+ methods is that +build+
+      # supports STI (Single table inheritance) and looks at the inheritance
+      # field. So it can build a model of actual class. For instance:
+      #
+      #   class Employee
+      #     include Dynamoid::Document
+      #
+      #     field :type
+      #     field :name
+      #   end
       #
+      #   class Manager < Employee
+      #   end
+      #
+      #   Employee.build(name: 'Alice', type: 'Manager') # => #<Manager:0x00007f945756e3f0 ...>
+      #
+      # @param attrs [Hash] Attributes with which to create the document
+      # @param block [Proc] Block to process a document after initialization
+      # @return [Dynamoid::Document] the new document
       # @since 0.2.0
-      def build(attrs = {})
-        choose_right_class(attrs).new(attrs)
+      def build(attrs = {}, &block)
+        choose_right_class(attrs).new(attrs, &block)
       end
 
-      # Does this object exist?
+      # Does this model exist in a table?
+      #
+      #   User.exists?('713') # => true
       #
-      # Supports primary key in format that `find` call understands.
-      # Multiple keys and single compound primary key should be passed only as Array explicitily.
+      # If a range key is declared it should be specified in the following way:
       #
-      # Supports conditions in format that `where` call understands.
+      #   User.exists?([['713', 'range-key-value']]) # => true
       #
-      # @param [Mixed] id_or_conditions the id of the object or a hash with the options to filter from.
+      # It's possible to check existence of several models at once:
       #
-      # @return [Boolean] true/false
+      #   User.exists?(['713', '714', '715'])
       #
-      # @example With id
+      # Or in case when a range key is declared:
       #
-      #   Post.exist?(713)
-      #   Post.exist?([713, 210])
+      #   User.exists?(
+      #     [
+      #       ['713', 'range-key-value-1'],
+      #       ['714', 'range-key-value-2'],
+      #       ['715', 'range-key-value-3']
+      #     ]
+      #   )
       #
-      # @example With attributes conditions
+      # It's also possible to specify models not with primary key but with
+      # conditions on the attributes (in the +where+ method style):
       #
-      #   Post.exist?(version: 1, 'created_at.gt': Time.now - 1.day)
+      #   User.exists?(age: 20, 'created_at.gt': Time.now - 1.day)
       #
+      # @param id_or_conditions [String|Array[String]|Array[Array]|Hash] the primary id of the model, a list of primary ids or a hash with the options to filter from.
+      # @return [true|false]
       # @since 0.2.0
       def exists?(id_or_conditions = {})
         case id_or_conditions
@@ -121,10 +166,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def deep_subclasses
         subclasses + subclasses.map(&:deep_subclasses).flatten
       end
 
+      # @private
       def choose_right_class(attrs)
         attrs[inheritance_field] ? attrs[inheritance_field].constantize : self
       end
@@ -132,12 +179,20 @@ module Dynamoid #:nodoc:
 
     # Initialize a new object.
     #
-    # @param [Hash] attrs Attributes with which to create the object.
+    #   User.new(name: 'A')
     #
+    # Initialize an object and pass it into a block to set other attributes.
+    #
+    #   User.new(name: 'A') do |u|
+    #     u.age = 21
+    #   end
+    #
+    # @param attrs [Hash] Attributes with which to create the document
+    # @param block [Proc] Block to process a document after initialization
     # @return [Dynamoid::Document] the new document
     #
     # @since 0.2.0
-    def initialize(attrs = {})
+    def initialize(attrs = {}, &block)
       run_callbacks :initialize do
         @new_record = true
         @attributes ||= {}
@@ -155,11 +210,19 @@ module Dynamoid #:nodoc:
         attrs_virtual = attrs.slice(*(attrs.keys - self.class.attributes.keys))
 
         load(attrs_with_defaults.merge(attrs_virtual))
+
+        if block
+          block.call(self)
+        end
       end
     end
 
-    # An object is equal to another object if their ids are equal.
+    # Check equality of two models.
     #
+    # A model is equal to another model only if their primary keys (hash key
+    # and optionaly range key) are equal.
+    #
+    # @return [true|false]
     # @since 0.2.0
     def ==(other)
       if self.class.identity_map_on?
@@ -171,36 +234,54 @@ module Dynamoid #:nodoc:
       end
     end
 
+    # Check equality of two models.
+    #
+    # Works exactly like +==+ does.
+    #
+    # @return [true|false]
     def eql?(other)
       self == other
     end
 
+    # Generate an Integer hash value for this model.
+    #
+    # Hash value is based on primary key. So models can be used safely as a
+    # +Hash+ keys.
+    #
+    # @return [Integer]
     def hash
       hash_key.hash ^ range_value.hash
     end
 
-    # Return an object's hash key, regardless of what it might be called to the object.
+    # Return a model's hash key value.
     #
     # @since 0.4.0
     def hash_key
-      send(self.class.hash_key)
+      self[self.class.hash_key.to_sym]
     end
 
-    # Assign an object's hash key, regardless of what it might be called to the object.
+    # Assign a model's hash key value, regardless of what it might be called to
+    # the object.
     #
     # @since 0.4.0
     def hash_key=(value)
-      send("#{self.class.hash_key}=", value)
+      self[self.class.hash_key.to_sym] = value
     end
 
+    # Return a model's range key value.
+    #
+    # Returns +nil+ if a range key isn't declared for a model.
     def range_value
-      if range_key = self.class.range_key
-        send(range_key)
+      if self.class.range_key
+        self[self.class.range_key.to_sym]
       end
     end
 
+    # Assign a model's range key value.
     def range_value=(value)
-      send("#{self.class.range_key}=", value)
+      if self.class.range_key
+        self[self.class.range_key.to_sym] = value
+      end
     end
 
     private
@@ -212,7 +293,7 @@ module Dynamoid #:nodoc:
     # Evaluates the default value given, this is used by undump
     # when determining the value of the default given for a field options.
     #
-    # @param [Object] :value the attribute's default value
+    # @param val [Object] the attribute's default value
     def evaluate_default_value(val)
       if val.respond_to?(:call)
         val.call