dynamoid 0.2.0 → 0.3.0

data/lib/dynamoid/associations/belongs_to.rb

@@ -1,15 +1,24 @@
 # encoding: utf-8
 module Dynamoid #:nodoc:
 
-  # The BelongsTo association.
+  # 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
     class BelongsTo
       include Dynamoid::Associations::Association
       
+      # Is this object equal to the association's target?
+      #
+      # @return [Boolean] true/false
+      #
+      # @since 0.2.0
       def ==(other)
         target == other
       end
       
+      # Delegate methods we don't find directly to the target.
+      #
+      # @since 0.2.0
       def method_missing(method, *args)
         if target.respond_to?(method)
           target.send(method, *args)
@@ -20,28 +29,45 @@ module Dynamoid #:nodoc:
       
       private
       
+      # Find the target of the belongs_to association.
+      #
+      # @return [Dynamoid::Document] the found target (or nil if nothing)
+      #
+      # @since 0.2.0
       def target
         records.first
       end
       
+      # Find the target association, either has_many or has_one. Uses either options[:inverse_of] or the source class name and default parsing to
+      # return the most likely name for the target association.
+      #
+      # @since 0.2.0
       def target_association
-        has_many_key_name = source.class.to_s.pluralize.downcase.to_sym
-        has_one_key_name = source.class.to_s.downcase.to_sym
+        has_many_key_name = options[:inverse_of] || source.class.to_s.underscore.pluralize.to_sym
+        has_one_key_name = options[:inverse_of] || source.class.to_s.underscore.to_sym
         if !target_class.associations[has_many_key_name].nil?
           return has_many_key_name if target_class.associations[has_many_key_name][:type] == :has_many
-        elsif !target_class.associations[has_one_key_name].nil?
+        end
+
+        if !target_class.associations[has_one_key_name].nil?
           return has_one_key_name if target_class.associations[has_one_key_name][:type] == :has_one
         end
       end
       
+      # Associate a source object to this association.
+      #
+      # @since 0.2.0
       def associate_target(object)
         object.update_attribute(target_attribute, target_ids.merge(Array(source.id)))
       end
-      
+
+      # Disassociate a source object from this association.
+      #
+      # @since 0.2.0      
       def disassociate_target(object)
         source.update_attribute(source_attribute, target_ids - Array(source.id))
       end
     end
   end
   
-end
+end

data/lib/dynamoid/associations/has_and_belongs_to_many.rb

@@ -1,29 +1,55 @@
 # encoding: utf-8
 module Dynamoid #:nodoc:
 
-  # The habtm association.
+  # The has and belongs to many association.
   module Associations
     class HasAndBelongsToMany
       include Dynamoid::Associations::Association
       
+      # Is this array equal to the association's records?
+      #
+      # @return [Boolean] true/false
+      #
+      # @since 0.2.0
       def ==(other)
         records == Array(other)
       end
       
+      # Delegate methods we don't find directly to the records array.
+      #
+      # @since 0.2.0
+      def method_missing(method, *args)
+        if records.respond_to?(method)
+          records.send(method, *args)
+        else
+          super
+        end
+      end
+      
       private
       
+      # Find the target association, always another :has_and_belongs_to_many association. Uses either options[:inverse_of] or the source class name 
+      # and default parsing to return the most likely name for the target association.
+      #
+      # @since 0.2.0
       def target_association
-        key_name = source.class.to_s.pluralize.downcase.to_sym
+        key_name = options[:inverse_of] || source.class.to_s.pluralize.underscore.to_sym
         guess = target_class.associations[key_name]
         return nil if guess.nil? || guess[:type] != :has_and_belongs_to_many
         key_name
       end
             
+      # Associate a source object to this association.
+      #
+      # @since 0.2.0      
       def associate_target(object)
         ids = object.send(target_attribute) || Set.new
         object.update_attribute(target_attribute, ids.merge(Array(source.id)))
       end
       
+      # Disassociate a source object from this association.
+      #
+      # @since 0.2.0
       def disassociate_target(object)
         ids = object.send(target_attribute) || Set.new
         object.update_attribute(target_attribute, ids - Array(source.id))
@@ -31,4 +57,4 @@ module Dynamoid #:nodoc:
     end
   end
   
-end
+end

data/lib/dynamoid/associations/has_many.rb

@@ -1,28 +1,54 @@
 # encoding: utf-8
 module Dynamoid #:nodoc:
 
-  # The HasMany association.
+  # The has_many association.
   module Associations
     class HasMany
       include Dynamoid::Associations::Association
       
+      # Is this array equal to the association's records?
+      #
+      # @return [Boolean] true/false
+      #
+      # @since 0.2.0
       def ==(other)
         records == Array(other)
       end
 
+      # Delegate methods we don't find directly to the records array.
+      #
+      # @since 0.2.0
+      def method_missing(method, *args)
+        if records.respond_to?(method)
+          records.send(method, *args)
+        else
+          super
+        end
+      end
+
       private
 
+      # Find the target association, always a :belongs_to association. Uses either options[:inverse_of] or the source class name 
+      # and default parsing to return the most likely name for the target association.
+      #
+      # @since 0.2.0
       def target_association
-        key_name = source.class.to_s.singularize.downcase.to_sym
+        key_name = options[:inverse_of] || source.class.to_s.singularize.underscore.to_sym
         guess = target_class.associations[key_name]
         return nil if guess.nil? || guess[:type] != :belongs_to
         key_name
       end
-            
+
+      # Associate a source object to this association.
+      #
+      # @since 0.2.0                  
       def associate_target(object)
         object.update_attribute(target_attribute, Set[source.id])
       end
       
+      # Disassociate a source object from this association.
+      #
+      # @since 0.2.0      
       def disassociate_target(object)
         object.update_attribute(target_attribute, nil)
       end
@@ -30,4 +56,4 @@ module Dynamoid #:nodoc:
     end
   end
   
-end
+end

data/lib/dynamoid/associations/has_one.rb

@@ -6,10 +6,18 @@ module Dynamoid #:nodoc:
     class HasOne
       include Dynamoid::Associations::Association
       
+      # Is this object equal to the association's target?
+      #
+      # @return [Boolean] true/false
+      #
+      # @since 0.2.0
       def ==(other)
         target == other
       end
 
+      # Delegate methods we don't find directly to the target.
+      #
+      # @since 0.2.0
       def method_missing(method, *args)
         if target.respond_to?(method)
           target.send(method, *args)
@@ -20,21 +28,36 @@ module Dynamoid #:nodoc:
       
       private
       
+      # Find the target of the has_one association.
+      #
+      # @return [Dynamoid::Document] the found target (or nil if nothing)
+      #
+      # @since 0.2.0
       def target
         records.first
       end
-      
+
+      # Find the target association, always a :belongs_to association. Uses either options[:inverse_of] or the source class name 
+      # and default parsing to return the most likely name for the target association.
+      #
+      # @since 0.2.0      
       def target_association
-        key_name = source.class.to_s.singularize.downcase.to_sym
+        key_name = options[:inverse_of] || source.class.to_s.singularize.underscore.to_sym
         guess = target_class.associations[key_name]
         return nil if guess.nil? || guess[:type] != :belongs_to
         key_name
       end
       
+      # Associate a source object to this association.
+      #
+      # @since 0.2.0      
       def associate_target(object)
-        object.update_attribute(target_attribute, source.id)
+        object.update_attribute(target_attribute, Set[source.id])
       end
       
+      # Disassociate a source object from this association.
+      #
+      # @since 0.2.0      
       def disassociate_target(object)
         source.update_attribute(source_attribute, nil)
       end

data/lib/dynamoid/components.rb

@@ -1,10 +1,11 @@
 # encoding: utf-8
-module Dynamoid #:nodoc
-  module Components #:nodoc
+module Dynamoid
+  
+  # All modules that a Document is composed of are defined in this
+  # module, to keep the document class from getting too cluttered.
+  module Components
     extend ActiveSupport::Concern
 
-    # All modules that a +Document+ is composed of are defined in this
-    # module, to keep the document class from getting too cluttered.
     included do
       extend ActiveModel::Translation
       extend ActiveModel::Callbacks
@@ -16,10 +17,10 @@ module Dynamoid #:nodoc
     end
 
     include ActiveModel::Conversion
+    include ActiveModel::Dirty
     include ActiveModel::MassAssignmentSecurity
     include ActiveModel::Naming
     include ActiveModel::Observing
-    include ActiveModel::Validations
     include ActiveModel::Serializers::JSON
     include ActiveModel::Serializers::Xml
     include Dynamoid::Fields
@@ -28,5 +29,6 @@ module Dynamoid #:nodoc
     include Dynamoid::Finders
     include Dynamoid::Associations
     include Dynamoid::Criteria
+    include Dynamoid::Validations
   end
 end

data/lib/dynamoid/config.rb

@@ -2,31 +2,44 @@
 require "uri"
 require "dynamoid/config/options"
 
-module Dynamoid #:nodoc
+module Dynamoid
   
+  # Contains all the basic configuration information required for Dynamoid: both sensible defaults and required fields.
   module Config
     extend self
     extend Options
     include ActiveModel::Observing
 
+    # All the default options.
     option :adapter, :default => 'local'
     option :namespace, :default => defined?(Rails) ? "dynamoid_#{Rails.application.class.parent_name}_#{Rails.env}" : "dynamoid"
     option :logger, :default => defined?(Rails)
     option :access_key
     option :secret_key
+    option :read_capacity, :default => 100
+    option :write_capacity, :default => 20
     option :warn_on_scan, :default => true
     option :partitioning, :default => false
     option :partition_size, :default => 200
     option :included_models, :default => []
     
+    # The default logger for Dynamoid: either the Rails logger or just stdout.
+    #
+    # @since 0.2.0
     def default_logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : ::Logger.new($stdout)
     end
 
+    # Returns the assigned logger instance.
+    #
+    # @since 0.2.0
     def logger
       @logger ||= default_logger
     end
     
+    # If you want to, set the logger manually to any output you'd like. Or pass false or nil to disable logging entirely.
+    #
+    # @since 0.2.0
     def logger=(logger)
       case logger
       when false, nil then @logger = nil
@@ -37,4 +50,4 @@ module Dynamoid #:nodoc
     end
 
   end
-end
+end

data/lib/dynamoid/config/options.rb

@@ -11,6 +11,8 @@ module Dynamoid #:nodoc
       #   options.defaults
       #
       # @return [ Hash ] The default options.
+      #
+      # @since 0.2.0
       def defaults
         @defaults ||= {}
       end
@@ -24,6 +26,8 @@ module Dynamoid #:nodoc
       # @param [ Hash ] options Extras for the option.
       #
       # @option options [ Object ] :default The default value.
+      #
+      # @since 0.2.0
       def option(name, options = {})
         defaults[name] = settings[name] = options[:default]
 
@@ -52,6 +56,8 @@ module Dynamoid #:nodoc
       #   config.reset
       #
       # @return [ Hash ] The defaults.
+      #
+      # @since 0.2.0
       def reset
         settings.replace(defaults)
       end
@@ -62,6 +68,8 @@ module Dynamoid #:nodoc
       #   options.settings
       #
       # @return [ Hash ] The setting options.
+      #
+      # @since 0.2.0
       def settings
         @settings ||= {}
       end

data/lib/dynamoid/criteria.rb

@@ -1,14 +1,19 @@
 # encoding: utf-8
 require 'dynamoid/criteria/chain'
 
-module Dynamoid #:nodoc:
+module Dynamoid
 
-  # This module defines criteria and criteria chains.
+  # Allows classes to be queried by where, all, first, and each and return criteria chains.
   module Criteria
     extend ActiveSupport::Concern
     
     module ClassMethods
+      
       [:where, :all, :first, :each].each do |meth|
+        # Return a criteria chain in response to a method that will begin or end a chain. For more information, 
+        # see Dynamoid::Criteria::Chain.
+        #
+        # @since 0.2.0
         define_method(meth) do |*args|
           chain = Dynamoid::Criteria::Chain.new(self)
           if args

data/lib/dynamoid/criteria/chain.rb

@@ -2,41 +2,75 @@
 module Dynamoid #:nodoc:
   module Criteria
 
-    # The class object that gets passed around indicating state of a building query.
-    # Also provides query execution.
+    # The criteria chain is equivalent to an ActiveRecord relation (and realistically I should change the name from
+    # chain to relation). It is a chainable object that builds up a query and eventually executes it either on an index
+    # or by a full table scan.
     class Chain
       attr_accessor :query, :source, :index, :values
       include Enumerable
       
+      # Create a new criteria chain.
+      #
+      # @param [Class] source the class upon which the ultimate query will be performed.
       def initialize(source)
         @query = {}
         @source = source
       end
       
+      # The workhorse method of the criteria chain. Each key in the passed in hash will become another criteria that the 
+      # ultimate query must match. A key can either be a symbol or a string, and should be an attribute name or 
+      # an attribute name with a range operator. 
+      #
+      # @example A simple criteria
+      #   where(:name => 'Josh')
+      #
+      # @example A more complicated criteria
+      #   where(:name => 'Josh', 'created_at.gt' => DateTime.now - 1.day)
+      #
+      # @since 0.2.0
       def where(args)
         args.each {|k, v| query[k] = v}
         self
       end
       
+      # Returns all the records matching the criteria.
+      #
+      # @since 0.2.0
       def all
         records
       end
-      
+
+      # Returns the first record matching the criteria.
+      #
+      # @since 0.2.0      
       def first
         records.first
       end
-      
+
+      # Allows you to use the results of a search as an enumerable over the results found.
+      #
+      # @since 0.2.0            
       def each(&block)
         records.each(&block)
       end
       
       private
       
+      # The actual records referenced by the association.
+      #
+      # @return [Array] an array of the found records.
+      #
+      # @since 0.2.0
       def records
         return records_with_index if index
         records_without_index
       end
-      
+
+      # If the query matches an index on the associated class, then this method will retrieve results from the index table.
+      #
+      # @return [Array] an array of the found records.
+      #
+      # @since 0.2.0      
       def records_with_index
         ids = if index.range_key?
           Dynamoid::Adapter.query(index.table_name, index_query).collect{|r| r[:ids]}.inject(Set.new) {|set, result| set + result}
@@ -55,14 +89,24 @@ module Dynamoid #:nodoc:
         end
       end
       
+      # If the query does not match an index, we'll manually scan the associated table to manually find results.
+      #
+      # @return [Array] an array of the found records.
+      #
+      # @since 0.2.0      
       def records_without_index
         if Dynamoid::Config.warn_on_scan
           Dynamoid.logger.warn 'Queries without an index are forced to use scan and are generally much slower than indexed queries!'
           Dynamoid.logger.warn "You can index this query by adding this to #{source.to_s.downcase}.rb: index [#{source.attributes.sort.collect{|attr| ":#{attr}"}.join(', ')}]"
         end
-        Dynamoid::Adapter.scan(source.table_name, query).collect {|hash| source.new(hash)}
+        Dynamoid::Adapter.scan(source.table_name, query).collect {|hash| source.new(hash).tap { |r| r.new_record = false } }
       end
       
+      # Format the provided query so that it can be used to query results from DynamoDB. 
+      #
+      # @return [Hash] a hash with keys of :hash_value and :range_value
+      #
+      # @since 0.2.0      
       def index_query
         values = index.values(query)
         {}.tap do |hash|
@@ -91,7 +135,10 @@ module Dynamoid #:nodoc:
           end
         end
       end
-      
+
+      # Return an index that fulfills all the attributes the criteria is querying, or nil if none is found.
+      #
+      # @since 0.2.0            
       def index
         index = source.find_index(query.keys.collect{|k| k.to_s.split('.').first})
         return nil if index.blank?
@@ -101,4 +148,4 @@ module Dynamoid #:nodoc:
     
   end
   
-end
+end