dynamoid 0.2.0 → 0.3.0

data/lib/dynamoid/document.rb

@@ -12,34 +12,95 @@ module Dynamoid #:nodoc:
     end
     
     module ClassMethods
+
+      # Initialize a new object and immediately save it to the database.
+      #
+      # @param [Hash] attrs Attributes with which to create the object.
+      #
+      # @return [Dynamoid::Document] the saved document
+      #
+      # @since 0.2.0
       def create(attrs = {})
         obj = self.new(attrs)
         obj.run_callbacks(:create) do
-          obj.save && obj.new_record = false
+          obj.save
+        end
+        obj
+      end
+
+      # Initialize a new object and immediately save it to the database. Raise an exception if persistence failed.
+      #
+      # @param [Hash] attrs Attributes with which to create the object.
+      #
+      # @return [Dynamoid::Document] the saved document
+      #
+      # @since 0.2.0
+      def create!(attrs = {})
+        obj = self.new(attrs)
+        obj.run_callbacks(:create) do
+          obj.save!
         end
         obj
       end
       
+      # Initialize a new object.
+      #
+      # @param [Hash] attrs Attributes with which to create the object.
+      #
+      # @return [Dynamoid::Document] the new document
+      #
+      # @since 0.2.0
       def build(attrs = {})
         self.new(attrs)
       end
+
+      # Does this object exist?
+      #
+      # @param [String] id the id of the object
+      #
+      # @return [Boolean] true/false
+      #
+      # @since 0.2.0
+      def exists?(id)
+        !! find(id)
+      end
     end
-    
+
+    # Initialize a new object.
+    #
+    # @param [Hash] attrs Attributes with which to create the object.
+    #
+    # @return [Dynamoid::Document] the new document
+    #
+    # @since 0.2.0    
     def initialize(attrs = {})
       @new_record = true
       @attributes ||= {}
-      attrs = self.class.undump(attrs)
-      self.class.attributes.keys.each {|att| write_attribute(att, attrs[att])}
+      incoming_attributes = self.class.undump(attrs)
+
+      self.class.attributes.keys.each do |attribute|
+        send "#{attribute}=", incoming_attributes[attribute]
+      end
     end
-    
+
+    # An object is equal to another object if their ids are equal.
+    #
+    # @since 0.2.0    
     def ==(other)
+      return false if other.nil?
       other.respond_to?(:id) && other.id == self.id
     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.
+    #
+    # @return [Dynamoid::Document] the document this method was called on
+    #
+    # @since 0.2.0        
     def reload
       self.attributes = self.class.find(self.id).attributes
       self
     end
   end
   
-end
+end

data/lib/dynamoid/errors.rb

@@ -1,8 +1,23 @@
 # encoding: utf-8
 module Dynamoid
+  
+  # All the error specific to Dynamoid.
   module Errors
+    
+    # Generic error class.
+    class Error < StandardError; end
+    
+    # InvalidField is raised when an attribute is specified for an index, but the attribute does not exist.
+    class InvalidField < Error; end
+    
+    # MissingRangeKey is raised when a table that requires a range key is quieried without one.
+    class MissingRangeKey < Error; end
 
-    class InvalidField < Exception; end
-    class MissingRangeKey < Exception; end
+    # DocumentNotValid is raised when the document fails validation.
+    class DocumentNotValid < Error
+      def initialize(document)
+        super("Validation failed: #{document.errors.full_messages.join(", ")}")
+      end
+    end
   end
 end

data/lib/dynamoid/fields.rb

@@ -1,9 +1,12 @@
 # encoding: utf-8
 module Dynamoid #:nodoc:
 
+  # All fields on a Dynamoid::Document must be explicitly defined -- if you have fields in the database that are not 
+  # specified with field, then they will be ignored.
   module Fields
     extend ActiveSupport::Concern
 
+    # Initialize the attributes we know the class has, in addition to our magic attributes: id, created_at, and updated_at.
     included do
       class_attribute :attributes
       
@@ -14,6 +17,15 @@ module Dynamoid #:nodoc:
     end
     
     module ClassMethods
+      
+      # Specify a field for a document. Its type determines how it is coerced when read in and out of the datastore: 
+      # default is string, but you can also specify :integer, :float, :set, :array, :datetime, and :serialized.
+      #
+      # @param [Symbol] name the name of the field
+      # @param [Symbol] type the type of the field (one of :integer, :float, :set, :array, :datetime, or :serialized)
+      # @param [Hash] options any additional options for the field
+      #
+      # @since 0.2.0
       def field(name, type = :string, options = {})
         named = name.to_s
         self.attributes[name] = {:type => type}.merge(options)
@@ -26,27 +38,52 @@ module Dynamoid #:nodoc:
         define_method("#{named}?") do
           !read_attribute(named).nil?
         end
+        define_attribute_methods(self.attributes.keys)
       end
     end
     
+    # You can access the attributes of an object directly on its attributes method, which is by default an empty hash.
     attr_accessor :attributes
     alias :raw_attributes :attributes
 
+    # Write an attribute on the object. Also marks the previous value as dirty.
+    #
+    # @param [Symbol] name the name of the field
+    # @param [Object] value the value to assign to that field
+    #
+    # @since 0.2.0
     def write_attribute(name, value)
+      self.send("#{name}_will_change!".to_sym) unless self.read_attribute(name) == value
       attributes[name.to_sym] = value
     end
     alias :[]= :write_attribute
 
+    # Read an attribute from an object.
+    #
+    # @param [Symbol] name the name of the field
+    #
+    # @since 0.2.0
     def read_attribute(name)
       attributes[name.to_sym]
     end
     alias :[] :read_attribute
 
+    # Updates multiple attibutes at once, saving the object once the updates are complete.
+    #
+    # @param [Hash] attributes a hash of attributes to update
+    #
+    # @since 0.2.0
     def update_attributes(attributes)
       attributes.each {|attribute, value| self.write_attribute(attribute, value)}
       save
     end
 
+    # Update a single attribute, saving the object afterwards.
+    #
+    # @param [Symbol] attribute the attribute to update
+    # @param [Object] value the value to assign it
+    #
+    # @since 0.2.0
     def update_attribute(attribute, value)
       write_attribute(attribute, value)
       save
@@ -54,10 +91,16 @@ module Dynamoid #:nodoc:
     
     private
     
+    # Automatically called during the created callback to set the created_at time.
+    #
+    # @since 0.2.0
     def set_created_at
       self.created_at = DateTime.now
     end
-    
+
+    # Automatically called during the save callback to set the updated_at time.
+    #
+    # @since 0.2.0    
     def set_updated_at
       self.updated_at = DateTime.now
     end

data/lib/dynamoid/finders.rb

@@ -1,22 +1,37 @@
 # encoding: utf-8
-module Dynamoid #:nodoc:
+module Dynamoid
 
   # This module defines the finder methods that hang off the document at the
-  # class level.
+  # class level, like find, find_by_id, and the method_missing style finders.
   module Finders
     extend ActiveSupport::Concern
     
     module ClassMethods
+      
+      # Find one or many objects, specified by one id or an array of ids.
+      #
+      # @param [Array/String] *id an array of ids or one single id
+      #
+      # @return [Dynamoid::Document] one object or an array of objects, depending on whether the input was an array or not
+      #
+      # @since 0.2.0
       def find(*id)
         id = Array(id.flatten.uniq)
         if id.count == 1
           self.find_by_id(id.first)
         else
           items = Dynamoid::Adapter.read(self.table_name, id)
-          items[self.table_name].collect{|i| o = self.build(i); o.new_record = false; o}
+          items[self.table_name].collect{|i| self.build(i).tap { |o| o.new_record = false } }
         end
       end
-      
+
+      # Find one object directly by id.
+      #
+      # @param [String] id the id of the object to find
+      #
+      # @return [Dynamoid::Document] the found object, or nil if nothing was found
+      #
+      # @since 0.2.0      
       def find_by_id(id)
         if item = Dynamoid::Adapter.read(self.table_name, id)
           obj = self.new(item)
@@ -26,7 +41,18 @@ module Dynamoid #:nodoc:
           return nil
         end
       end
-      
+
+      # Find using exciting method_missing finders attributes. Uses criteria chains under the hood to accomplish this neatness.
+      #
+      # @example find a user by a first name
+      #   User.find_by_first_name('Josh')
+      #
+      # @example find all users by first and last name
+      #   User.find_all_by_first_name_and_last_name('Josh', 'Symonds')
+      #
+      # @return [Dynamoid::Document/Array] the found object, or an array of found objects if all was somewhere in the method
+      #
+      # @since 0.2.0            
       def method_missing(method, *args)
         if method =~ /find/
           finder = method.to_s.split('_by_').first
@@ -47,4 +73,4 @@ module Dynamoid #:nodoc:
     end
   end
   
-end
+end

data/lib/dynamoid/indexes.rb

@@ -3,10 +3,13 @@ require 'dynamoid/indexes/index'
 
 module Dynamoid #:nodoc:
 
-  # Builds all indexes present on the model.
+  # Indexes are quick ways of performing queries by anything other than id in DynamoDB. They are denormalized tables; 
+  # that is, data is duplicated in the initial table (where the object is saved) and the index table (where 
+  # we perform indexing). 
   module Indexes
     extend ActiveSupport::Concern
 
+    # Make some helpful attributes to persist indexes.
     included do
       class_attribute :indexes
       
@@ -14,16 +17,27 @@ module Dynamoid #:nodoc:
     end
     
     module ClassMethods
+      
+      # The call to create an index. Generates a new index with the specified options -- for more information, see Dynamoid::Indexes::Index.
+      # This function also attempts to immediately create the indexing table if it does not exist already.
+      #
+      # @since 0.2.0
       def index(name, options = {})
         index = Dynamoid::Indexes::Index.new(self, name, options)
         self.indexes[index.name] = index
         create_indexes        
       end
       
+      # Helper function to find indexes.
+      #
+      # @since 0.2.0
       def find_index(index)
         self.indexes[Array(index).collect(&:to_s).sort.collect(&:to_sym)]
       end
       
+      # Helper function to create indexes (if they don't exist already).
+      #
+      # @since 0.2.0
       def create_indexes
         self.indexes.each do |name, index|
           opts = index.range_key? ? {:range_key => :range} : {}
@@ -32,12 +46,18 @@ module Dynamoid #:nodoc:
       end
     end
     
+    # Callback for an object to save itself to each of a class' indexes.
+    #
+    # @since 0.2.0
     def save_indexes
       self.class.indexes.each do |name, index|
         index.save(self)
       end
     end
-    
+
+    # Callback for an object to delete itself from each of a class' indexes.
+    #
+    # @since 0.2.0    
     def delete_indexes
       self.class.indexes.each do |name, index|
         index.delete(self)

data/lib/dynamoid/indexes/index.rb

@@ -2,11 +2,17 @@
 module Dynamoid #:nodoc:
   module Indexes
 
-    # The class abstracts information about an index
+    # The class contains all the information an index contains, including its keys and which attributes it covers.
     class Index
       attr_accessor :source, :name, :hash_keys, :range_keys
       alias_method :range_key?, :range_keys
       
+      # Create a new index. Pass either :range => true or :range => :column_name to create a ranged index on that column.
+      #
+      # @param [Class] source the source class for the index
+      # @param [Symbol] name the name of the index
+      #
+      # @since 0.2.0      
       def initialize(source, name, options = {})
         @source = source
         
@@ -21,19 +27,45 @@ module Dynamoid #:nodoc:
         raise Dynamoid::Errors::InvalidField, 'A key specified for an index is not a field' unless keys.all?{|n| source.attributes.include?(n)}
       end
       
+      # Sort objects into alphabetical strings, used for composing index names correctly (since we always assume they're alphabetical).
+      #
+      # @example find all users by first and last name
+      #   sort([:gamma, :alpha, :beta, :omega]) # => [:alpha, :beta, :gamma, :omega]
+      #
+      # @since 0.2.0         
       def sort(objs)
         Array(objs).flatten.compact.uniq.collect(&:to_s).sort.collect(&:to_sym)
       end
-      
+
+      # Return the array of keys this index uses for its table.
+      #
+      # @since 0.2.0      
       def keys
         [Array(hash_keys) + Array(range_keys)].flatten.uniq
       end
       
+      # Return the table name for this index.
+      #
+      # @since 0.2.0
       def table_name
         "#{Dynamoid::Config.namespace}_index_#{source.to_s.downcase}_#{name.collect(&:to_s).collect(&:pluralize).join('_and_')}"
       end
-      
-      def values(attrs)
+
+      # Given either an object or a list of attributes, generate a hash key and a range key for the index. Optionally pass in 
+      # true to changed_attributes for a list of all the object's dirty attributes in convenient index form (for deleting stale 
+      # information from the indexes).
+      #
+      # @param [Object] attrs either an object that responds to :attributes, or a hash of attributes
+      #
+      # @return [Hash] a hash with the keys :hash_value and :range_value
+      #
+      # @since 0.2.0
+      def values(attrs, changed_attributes = false)
+        if changed_attributes
+          hash = {}
+          attrs.changes.each {|k, v| hash[k.to_sym] = (v.first || v.last)}
+          attrs = hash
+        end
         attrs = attrs.send(:attributes) if attrs.respond_to?(:attributes)
         {}.tap do |hash|
           hash[:hash_value] = hash_keys.collect{|key| attrs[key]}.join('.')
@@ -41,16 +73,25 @@ module Dynamoid #:nodoc:
         end
       end
       
+      # Save an object to this index, merging it with existing ids if there's already something present at this index location.
+      # First, though, delete this object from its old indexes (so the object isn't listed in an erroneous index).
+      #
+      # @since 0.2.0
       def save(obj)
+        self.delete(obj, true)
         values = values(obj)
         return true if values[:hash_value].blank? || (!values[:range_value].nil? && values[:range_value].blank?)
         existing = Dynamoid::Adapter.read(self.table_name, values[:hash_value], values[:range_value])
         ids = ((existing and existing[:ids]) or Set.new)
         Dynamoid::Adapter.write(self.table_name, {:id => values[:hash_value], :ids => ids.merge([obj.id]), :range => values[:range_value]})
       end
-      
-      def delete(obj)
-        values = values(obj)
+
+      # Delete an object from this index, preserving existing ids if there are any, and failing gracefully if for some reason the 
+      # index doesn't already have this object in it.
+      #
+      # @since 0.2.0      
+      def delete(obj, changed_attributes = false)
+        values = values(obj, changed_attributes)
         return true if values[:hash_value].blank? || (!values[:range_value].nil? && values[:range_value].blank?)
         existing = Dynamoid::Adapter.read(self.table_name, values[:hash_value], values[:range_value])
         return true unless existing && existing[:ids] && existing[:ids].include?(obj.id)