dynamoid 3.2.0 → 3.6.0

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
 
@@ -116,7 +118,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,13 @@ 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))
       end
 
+      # @private
       def records
         if query.empty?
           target
@@ -43,13 +47,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.
+      #
+      #   tag.posts.delete(post)
+      #   tag.posts.delete([post1, post2, post3])
       #
-      # @param [Dynamoid::Document] object the object (or array of objects) to remove 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.
       #
-      # @return [Dynamoid::Document] the deleted object
+      # 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 +70,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]
+      #
+      # This preserves the current records in the association (if any) and adds
+      # the object to the target association if it is detected to exist.
       #
-      # @return [Dynamoid::Document] the added object
+      # 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 +99,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 +109,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 +147,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 +167,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 +181,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 +207,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 +217,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

data/lib/dynamoid/associations/single_association.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   module Associations
     module SingleAssociation
       include Association
 
       delegate :class, to: :target
 
+      # @private
       def setter(object)
         if object.nil?
           delete
@@ -19,16 +20,37 @@ module Dynamoid #:nodoc:
         object
       end
 
+      # Delete a model from the association.
+      #
+      #   post.logo.delete # => nil
+      #
+      # Saves both models immediately - a source model and a target one so any
+      # unsaved changes will be saved. Doesn't delete an associated model from
+      # DynamoDB.
       def delete
         target.send(target_association).disassociate(source.hash_key) if target && target_association
         disassociate
         target
       end
 
+      # Create a new instance of the target class, persist it and associate.
+      #
+      #   post.logo.create!(hight: 50, width: 90)
+      #
+      # If the creation fails an exception will be raised.
+      #
+      # @param attributes [Hash] attributes of a model to create
+      # @return [Dynamoid::Document] created model
       def create!(attributes = {})
         setter(target_class.create!(attributes))
       end
 
+      # Create a new instance of the target class, persist it and associate.
+      #
+      #   post.logo.create(hight: 50, width: 90)
+      #
+      # @param attributes [Hash] attributes of a model to create
+      # @return [Dynamoid::Document] created model
       def create(attributes = {})
         setter(target_class.create(attributes))
       end
@@ -44,6 +66,7 @@ module Dynamoid #:nodoc:
 
       # Delegate methods we don't find directly to the target.
       #
+      # @private
       # @since 0.2.0
       def method_missing(method, *args)
         if target.respond_to?(method)
@@ -53,21 +76,25 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def nil?
         target.nil?
       end
 
+      # @private
       def empty?
         # This is needed to that ActiveSupport's #blank? and #present?
         # methods work as expected for SingleAssociations.
         target.nil?
       end
 
+      # @private
       def associate(hash_key)
         target.send(target_association).disassociate(source.hash_key) if target && target_association
         source.update_attribute(source_attribute, Set[hash_key])
       end
 
+      # @private
       def disassociate(_hash_key = nil)
         source.update_attribute(source_attribute, nil)
       end

data/lib/dynamoid/components.rb

@@ -3,6 +3,7 @@
 module Dynamoid
   # All modules that a Document is composed of are defined in this
   # module, to keep the document class from getting too cluttered.
+  # @private
   module Components
     extend ActiveSupport::Concern
 
@@ -14,24 +15,28 @@ module Dynamoid
 
       before_create :set_created_at
       before_save :set_updated_at
+      before_save :set_expires_field
       after_initialize :set_inheritance_field
     end
 
-    include ActiveModel::AttributeMethods
+    include ActiveModel::AttributeMethods # Actually it will be inclided in Dirty module again
     include ActiveModel::Conversion
     include ActiveModel::MassAssignmentSecurity if defined?(ActiveModel::MassAssignmentSecurity)
     include ActiveModel::Naming
     include ActiveModel::Observing if defined?(ActiveModel::Observing)
     include ActiveModel::Serializers::JSON
     include ActiveModel::Serializers::Xml if defined?(ActiveModel::Serializers::Xml)
+    include Dynamoid::Persistence
+    include Dynamoid::Loadable
+    # Dirty module should be included after Persistence and Loadable
+    # because it overrides some methods declared in these modules
+    include Dynamoid::Dirty
     include Dynamoid::Fields
     include Dynamoid::Indexes
-    include Dynamoid::Persistence
     include Dynamoid::Finders
     include Dynamoid::Associations
     include Dynamoid::Criteria
     include Dynamoid::Validations
     include Dynamoid::IdentityMap
-    include Dynamoid::Dirty
   end
 end

data/lib/dynamoid/config.rb

@@ -2,14 +2,23 @@
 
 require 'uri'
 require 'logger'
-require 'null_logger'
 require 'dynamoid/config/options'
 require 'dynamoid/config/backoff_strategies/constant_backoff'
 require 'dynamoid/config/backoff_strategies/exponential_backoff'
 
 module Dynamoid
   # Contains all the basic configuration information required for Dynamoid: both sensible defaults and required fields.
+  # @private
   module Config
+    # @since 3.3.1
+    DEFAULT_NAMESPACE = if defined?(Rails)
+                          klass = Rails.application.class
+                          app_name = Rails::VERSION::MAJOR >= 6 ? klass.module_parent_name : klass.parent_name
+                          "dynamoid_#{app_name}_#{Rails.env}"
+                        else
+                          'dynamoid'
+                        end
+
     extend self
 
     extend Options
@@ -17,11 +26,13 @@ module Dynamoid
 
     # All the default options.
     option :adapter, default: 'aws_sdk_v3'
-    option :namespace, default: defined?(Rails) ? "dynamoid_#{Rails.application.class.parent_name}_#{Rails.env}" : 'dynamoid'
+    option :namespace, default: DEFAULT_NAMESPACE
     option :access_key, default: nil
     option :secret_key, default: nil
+    option :credentials, default: nil
     option :region, default: nil
     option :batch_size, default: 100
+    option :capacity_mode, default: nil
     option :read_capacity, default: 100
     option :write_capacity, default: 20
     option :warn_on_scan, default: true
@@ -31,6 +42,7 @@ module Dynamoid
     option :sync_retry_max_times, default: 60 # a bit over 2 minutes
     option :sync_retry_wait_seconds, default: 2
     option :convert_big_decimal, default: false
+    option :store_attribute_with_nil_value, default: false # keep or ignore attribute with nil value at saving
     option :models_dir, default: './app/models' # perhaps you keep your dynamoid models in a different directory?
     option :application_timezone, default: :utc # available values - :utc, :local, time zone name like "Hawaii"
     option :dynamodb_timezone, default: :utc # available values - :utc, :local, time zone name like "Hawaii"
@@ -42,6 +54,7 @@ module Dynamoid
       constant: BackoffStrategies::ConstantBackoff,
       exponential: BackoffStrategies::ExponentialBackoff
     }
+    option :log_formatter, default: nil
     option :http_continue_timeout, default: nil # specify if you'd like to overwrite Aws Configure - default: 1
     option :http_idle_timeout, default: nil     #                                                  - default: 5
     option :http_open_timeout, default: nil     #                                                  - default: 15
@@ -66,7 +79,7 @@ module Dynamoid
     # @since 0.2.0
     def logger=(logger)
       case logger
-      when false, nil then @logger = NullLogger.new
+      when false, nil then @logger = ::Logger.new(nil)
       when true then @logger = default_logger
       else
         @logger = logger if logger.respond_to?(:info)