dynamoid 3.3.0 → 3.7.0

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/scan.rb

@@ -5,6 +5,7 @@ require_relative 'middleware/limit'
 require_relative 'middleware/start_key'
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class Scan
@@ -21,8 +22,8 @@ module Dynamoid
           request = build_request
 
           Enumerator.new do |yielder|
-            api_call = -> (request) do
-              client.scan(request).tap do |response|
+            api_call = lambda do |req|
+              client.scan(req).tap do |response|
                 yielder << response
               end
             end
@@ -85,6 +86,7 @@ module Dynamoid
 
         def attributes_to_get
           return if options[:project].nil?
+
           options[:project].map(&:to_s)
         end
       end

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/table.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       # Represents a table. Exposes data from the "DescribeTable" API call, and also

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/until_past_table_status.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class UntilPastTableStatus
@@ -32,7 +33,7 @@ module Dynamoid
           # See: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#describe_table-instance_method
           rescue Aws::DynamoDB::Errors::ResourceNotFoundException => e
             case status
-            when :creating then
+            when :creating
               if counter >= Dynamoid::Config.sync_retry_max_times
                 Dynamoid.logger.warn "Waiting on table metadata for #{table_name} (check #{counter})"
                 retry # start over at first line of begin, does not reset counter

data/lib/dynamoid/application_time_zone.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module ApplicationTimeZone
     def self.at(value)
       case Dynamoid::Config.application_timezone

data/lib/dynamoid/associations.rb

@@ -25,12 +25,55 @@ module Dynamoid
     end
 
     module ClassMethods
-      # create a has_many association for this document.
+      # Declare a +has_many+ association for this document.
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #   class Category
+      #     include Dynamoid::Document
+      #
+      #     has_many :posts
+      #   end
+      #
+      # Association is an enumerable collection and supports following addition
+      # operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +destroy_all+
+      # * +delete_all+
+      # * +delete+
+      # * +<<+
+      # * +where+
+      # * +all+
+      # * +empty?+
+      # * +size+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_many :labels, class: Tag
+      #   has_many :labels, class_name: 'Tag'
+      #
+      # When associated class has own +belongs_to+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :item, class_name: 'Tag'
+      #   end
+      #
+      #   class Tag
+      #     include Dynamoid::Document
+      #
+      #     has_many :posts, inverse_of: :item
+      #   end
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_many association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -38,12 +81,47 @@ module Dynamoid
         association(:has_many, name, options)
       end
 
-      # create a has_one association for this document.
+      # Declare a +has_one+ association for this document.
+      #
+      #   class Image
+      #     include Dynamoid::Document
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #     has_one :post
+      #   end
+      #
+      # Association supports following operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +delete+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_one :item, class: Post
+      #   has_one :item, class_name: 'Post'
+      #
+      # When associated class has own +belong_to+ association to the current
+      # class and the name doesn't match a name of the current class this name
+      # can be specified with +inverse_of+ option:
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :logo, class_name: 'Image'
+      #   end
+      #
+      #   class Image
+      #     include Dynamoid::Document
+      #
+      #     has_one :post, inverse_of: :logo
+      #   end
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_one association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -51,25 +129,110 @@ module Dynamoid
         association(:has_one, name, options)
       end
 
-      # create a belongs_to association for this document.
+      # Declare a +belongs_to+ association for this document.
+      #
+      #   class Post
+      #     include Dynamoid::Document
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #     belongs_to :categories
+      #   end
+      #
+      # Association supports following operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +delete+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   belongs_to :item, class: Post
+      #   belongs_to :item, class_name: 'Post'
+      #
+      # When associated class has own +has_many+ or +has_one+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Category
+      #     include Dynamoid::Document
+      #
+      #     has_many :items, class_name: 'Post'
+      #   end
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :categories, inverse_of: :items
+      #   end
+      #
+      # By default a hash key attribute name is +id+. If an associated class
+      # uses another name for a hash key attribute it should be specified in
+      # the +belongs_to+ association:
+      #
+      #   belongs_to :categories, foreign_key: :uuid
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_one association; that is, the has_many or has_one class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the has_many or has_one class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the has_many or has_one class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a has_many or has_one association, the name of that association
+      # @option options [Symbol] :foreign_key the name of a hash key attribute in the target class
       #
       # @since 0.2.0
       def belongs_to(name, options = {})
         association(:belongs_to, name, options)
       end
 
-      # create a has_and_belongs_to_many association for this document.
+      # Declare a +has_and_belongs_to_many+ association for this document.
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :tags
+      #   end
+      #
+      # Association is an enumerable collection and supports following addition
+      # operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +destroy_all+
+      # * +delete_all+
+      # * +delete+
+      # * +<<+
+      # * +where+
+      # * +all+
+      # * +empty?+
+      # * +size+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_and_belongs_to_many :labels, class: Tag
+      #   has_and_belongs_to_many :labels, class_name: 'Tag'
+      #
+      # When associated class has own +has_and_belongs_to_many+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Tag
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :items, class_name: 'Post'
+      #   end
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :tags, inverse_of: :items
+      #   end
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_and_belongs_to_many association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -81,9 +244,9 @@ module Dynamoid
 
       # create getters and setters for an association.
       #
-      # @param [Symbol] symbol the type (:has_one, :has_many, :has_and_belongs_to_many, :belongs_to) of the association
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor; see above for all valid options
+      # @param type [Symbol] the type (:has_one, :has_many, :has_and_belongs_to_many, :belongs_to) of the association
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor; see above for all valid options
       #
       # @since 0.2.0
       def association(type, name, options = {})

data/lib/dynamoid/associations/association.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The base association module which all associations include. Every association has two very important components: the source and
   # the target. The source is the object which is calling the association information. It always has the target_ids inside of an attribute on itself.
   # The target is the object which is referencing by this association.
+  # @private
   module Associations
+    # @private
     module Association
       attr_accessor :name, :options, :source, :loaded
 
@@ -56,6 +58,12 @@ module Dynamoid #:nodoc:
         :set
       end
 
+      def disassociate_source
+        Array(target).each do |target_entry|
+          target_entry.send(target_association).disassociate(source.hash_key) if target_entry && target_association
+        end
+      end
+
       private
 
       # The target class name, either inferred through the association's name or specified in options.
@@ -116,7 +124,7 @@ module Dynamoid #:nodoc:
 
       # Create a new instance of the target class without trying to add it to the association. This creates a base, that caller can update before setting or adding it.
       #
-      # @param [Hash] attribute hash for the new object
+      # @param attributes [Hash] attribute values for the new object
       #
       # @return [Dynamoid::Document] the newly-created object
       #

data/lib/dynamoid/associations/belongs_to.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The belongs_to association. For belongs_to, we reference only a single target instead of multiple records; that target is the
   # object to which the association object is associated.
   module Associations
+    # @private
     class BelongsTo
       include SingleAssociation
 

data/lib/dynamoid/associations/has_and_belongs_to_many.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The has and belongs to many association.
   module Associations
+    # @private
     class HasAndBelongsToMany
       include ManyAssociation
 

data/lib/dynamoid/associations/has_many.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The has_many association.
   module Associations
+    # @private
     class HasMany
       include ManyAssociation
 

data/lib/dynamoid/associations/has_one.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # The HasOne association.
   module Associations
+    # @private
     class HasOne
       include Association
       include SingleAssociation

data/lib/dynamoid/associations/many_association.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   module Associations
     module ManyAssociation
       include Association
@@ -13,6 +13,8 @@ module Dynamoid #:nodoc:
       end
 
       include Enumerable
+
+      # @private
       # Delegate methods to the records the association represents.
       delegate :first, :last, :empty?, :size, :class, to: :records
 
@@ -20,11 +22,15 @@ module Dynamoid #:nodoc:
       #
       # @return the association records; depending on which association this is, either a single instance or an array
       #
+      # @private
       # @since 0.2.0
       def find_target
-        Array(target_class.find(source_ids.to_a))
+        return [] if source_ids.empty?
+
+        Array(target_class.find(source_ids.to_a, raise_error: false))
       end
 
+      # @private
       def records
         if query.empty?
           target
@@ -43,13 +49,20 @@ module Dynamoid #:nodoc:
         records.include?(object)
       end
 
-      # Deletes an object or array of objects from the association. This removes their records from the association field on the source,
-      # and attempts to remove the source from the target association if it is detected to exist.
+      # Delete an object or array of objects from the association.
       #
-      # @param [Dynamoid::Document] object the object (or array of objects) to remove from the association
+      #   tag.posts.delete(post)
+      #   tag.posts.delete([post1, post2, post3])
       #
-      # @return [Dynamoid::Document] the deleted object
+      # This removes their records from the association field on the source,
+      # and attempts to remove the source from the target association if it is
+      # detected to exist.
       #
+      # It saves both models immediately - the source model and the target one
+      # so any not saved changes will be saved as well.
+      #
+      # @param object [Dynamoid::Document|Array] model (or array of models) to remove from the association
+      # @return [Dynamoid::Document|Array] the deleted model
       # @since 0.2.0
       def delete(object)
         disassociate(Array(object).collect(&:hash_key))
@@ -59,13 +72,19 @@ module Dynamoid #:nodoc:
         object
       end
 
-      # Add an object or array of objects to an association. This preserves the current records in the association (if any)
-      # and adds the object to the target association if it is detected to exist.
+      # Add an object or array of objects to an association.
       #
-      # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
+      #   tag.posts << post
+      #   tag.posts << [post1, post2, post3]
       #
-      # @return [Dynamoid::Document] the added object
+      # This preserves the current records in the association (if any) and adds
+      # the object to the target association if it is detected to exist.
       #
+      # It saves both models immediately - the source model and the target one
+      # so any not saved changes will be saved as well.
+      #
+      # @param object [Dynamoid::Document|Array] model (or array of models) to add to the association
+      # @return [Dynamoid::Document] the added model
       # @since 0.2.0
       def <<(object)
         associate(Array(object).collect(&:hash_key))
@@ -82,8 +101,9 @@ module Dynamoid #:nodoc:
       #
       # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
       #
-      # @return [Dynamoid::Document] the added object
+      # @return [Dynamoid::Document|Array] the added object
       #
+      # @private
       # @since 0.2.0
       def setter(object)
         target.each { |o| delete(o) }
@@ -91,23 +111,37 @@ module Dynamoid #:nodoc:
         object
       end
 
-      # Create a new instance of the target class and add it directly to the association. If the create fails an exception will be raised.
+      # Create a new instance of the target class, persist it and add directly
+      # to the association.
       #
-      # @param [Hash] attribute hash for the new object
+      #   tag.posts.create!(title: 'foo')
       #
-      # @return [Dynamoid::Document] the newly-created object
+      # Several models can be created at once when an array of attributes
+      # specified:
+      #
+      #   tag.posts.create!([{ title: 'foo' }, {title: 'bar'} ])
       #
+      # If the creation fails an exception will be raised.
+      #
+      # @param attributes [Hash] attribute values for the new object
+      # @return [Dynamoid::Document|Array] the newly-created object
       # @since 0.2.0
       def create!(attributes = {})
         self << target_class.create!(attributes)
       end
 
-      # Create a new instance of the target class and add it directly to the association.
+      # Create a new instance of the target class, persist it and add directly
+      # to the association.
       #
-      # @param [Hash] attribute hash for the new object
+      #   tag.posts.create(title: 'foo')
       #
-      # @return [Dynamoid::Document] the newly-created object
+      # Several models can be created at once when an array of attributes
+      # specified:
       #
+      #   tag.posts.create([{ title: 'foo' }, {title: 'bar'} ])
+      #
+      # @param attributes [Hash] attribute values for the new object
+      # @return [Dynamoid::Document|Array] the newly-created object
       # @since 0.2.0
       def create(attributes = {})
         self << target_class.create(attributes)
@@ -115,16 +149,18 @@ module Dynamoid #:nodoc:
 
       # Create a new instance of the target class and add it directly to the association. If the create fails an exception will be raised.
       #
-      # @param [Hash] attribute hash for the new object
-      #
       # @return [Dynamoid::Document] the newly-created object
       #
+      # @private
       # @since 0.2.0
       def each(&block)
         records.each(&block)
       end
 
-      # Destroys all members of the association and removes them from the association.
+      # Destroys all members of the association and removes them from the
+      # association.
+      #
+      #   tag.posts.destroy_all
       #
       # @since 0.2.0
       def destroy_all
@@ -133,7 +169,10 @@ module Dynamoid #:nodoc:
         objs.each(&:destroy)
       end
 
-      # Deletes all members of the association and removes them from the association.
+      # Deletes all members of the association and removes them from the
+      # association.
+      #
+      #   tag.posts.delete_all
       #
       # @since 0.2.0
       def delete_all
@@ -144,10 +183,13 @@ module Dynamoid #:nodoc:
 
       # Naive association filtering.
       #
-      # @param [Hash] A hash of attributes; each must match every returned object's attribute exactly.
+      #   tag.posts.where(title: 'foo')
       #
-      # @return [Dynamoid::Association] the association this method was called on (for chaining purposes)
+      # It loads lazily all the associated models and checks provided
+      # conditions. That's why only equality conditions can be specified.
       #
+      # @param args [Hash] A hash of attributes; each must match every returned object's attribute exactly.
+      # @return [Dynamoid::Association] the association this method was called on (for chaining purposes)
       # @since 0.2.0
       def where(args)
         filtered = clone
@@ -167,6 +209,7 @@ module Dynamoid #:nodoc:
 
       # Delegate methods we don't find directly to the records array.
       #
+      # @private
       # @since 0.2.0
       def method_missing(method, *args)
         if records.respond_to?(method)
@@ -176,10 +219,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def associate(hash_key)
         source.update_attribute(source_attribute, source_ids.merge(Array(hash_key)))
       end
 
+      # @private
       def disassociate(hash_key)
         source.update_attribute(source_attribute, source_ids - Array(hash_key))
       end