dynamoid 0.2.0 → 0.3.0

data/lib/dynamoid/adapter/local.rb

@@ -1,18 +1,37 @@
 module Dynamoid
   module Adapter
+    
+    # This gimpy hash construct should be equivalent to Amazon's actual DynamoDB, for offline development.
+    # All tests pass with either this or connecting to the real DynamoDB, and that's good enough for me.
     module Local
       extend self
-      # Gimpy hash that should be somewhat equivalent to what Amazon's actual DynamoDB, for offline development.
-    
+      
+      # The hash holding all of our data.
+      #
+      # @return [Hash] a hash of raw values
+      #
+      # @since 0.2.0
       def data
         @data ||= {}
       end
     
+      # A convenience method for testing that destroys all table data without destroying their structure.
+      #
+      # @since 0.2.0
       def reset_data
         self.data.each {|k, v| v[:data] = {}}
       end
     
-      # BatchGetItem
+      # Get many items at once from the hash.
+      # 
+      # @example Retrieve IDs 1 and 2 from the table testtable
+      #   Dynamoid::Adapter::Local.batch_get_item('table1' => ['1', '2'])
+      #
+      # @param [Hash] options the hash of tables and IDs to retrieve
+      #
+      # @return [Hash] a hash where keys are the table names and the values are the retrieved items
+      #
+      # @since 0.2.0
       def batch_get_item(options)
         Hash.new { |h, k| h[k] = Array.new }.tap do |hash|
           options.each do |table_name, keys|
@@ -30,24 +49,48 @@ module Dynamoid
         end
       end
     
-      # CreateTable
+      # Create a table.
+      #
+      # @param [String] table_name the name of the table to create
+      # @param [Symbol] key the table's primary key (defaults to :id)
+      # @param [Hash] options provide a range_key here if you want one for the table
+      #
+      # @since 0.2.0
       def create_table(table_name, key, options = {})
         data[table_name] = {:hash_key => key, :range_key => options[:range_key], :data => {}}
       end
     
-      # DeleteItem
+      # Removes an item from the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [String] key the hash key of the item to delete
+      # @param [Number] range_key the range key of the item to delete, required if the table has a composite key
+      #
+      # @since 0.2.0
       def delete_item(table_name, key, range_key = nil)
         data[table_name][:data].delete("#{key}.#{range_key}")
       end
     
-      # DeleteTable
+      # Deletes an entire table from the hash.
+      #
+      # @param [String] table_name the name of the table to destroy
+      #
+      # @since 0.2.0
       def delete_table(table_name)
         data.delete(table_name)
       end
     
-      # DescribeTable
+      # @todo Add a DescribeTable method.
     
-      # GetItem
+      # Fetches an item from the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [String] key the hash key of the item to find
+      # @param [Number] range_key the range key of the item to find, required if the table has a composite key
+      #
+      # @return [Hash] a hash representing the raw item
+      #
+      # @since 0.2.0
       def get_item(table_name, key, range_key = nil)
         if data[table_name][:data]
           data[table_name][:data]["#{key}.#{range_key}"]
@@ -56,19 +99,39 @@ module Dynamoid
         end
       end
     
-      # ListTables
+      # List all tables on DynamoDB.
+      #
+      # @since 0.2.0
       def list_tables
         data.keys
       end
     
-      # PutItem
+      # Persists an item in the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Object] object a hash or Dynamoid object to persist
+      #
+      # @since 0.2.0
       def put_item(table_name, object)
         table = data[table_name]
         table[:data][object[table[:hash_key]]]
         table[:data]["#{object[table[:hash_key]]}.#{object[table[:range_key]]}"] = object.delete_if{|k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?)}
       end
     
-      # Query
+      # Query the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Hash] opts the options to query the table with
+      # @option opts [String] :hash_value the value of the hash key to find
+      # @option opts [Range] :range_value find the range key within this range
+      # @option opts [Number] :range_greater_than find range keys greater than this
+      # @option opts [Number] :range_less_than find range keys less than this
+      # @option opts [Number] :range_gte find range keys greater than or equal to this
+      # @option opts [Number] :range_lte find range keys less than or equal to this
+      #
+      # @return [Array] an array of all matching items
+      #
+      # @since 0.2.0
       def query(table_name, opts = {})
         id = opts[:hash_value]
         range_key = data[table_name][:range_key]
@@ -87,16 +150,22 @@ module Dynamoid
         end
       end
     
-      # Scan
+      # Scan the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Hash] scan_hash a hash of attributes: matching records will be returned by the scan
+      #
+      # @return [Array] an array of all matching items
+      #
+      # @since 0.2.0
       def scan(table_name, scan_hash)
         return [] if data[table_name].nil?
         data[table_name][:data].values.flatten.select{|d| scan_hash.all?{|k, v| !d[k].nil? && d[k] == v}}
       end
     
-      # UpdateItem
-    
-      # UpdateTable
+      # @todo Add an UpdateItem method.
     
+      # @todo Add an UpdateTable method.
     end
   end
 end

data/lib/dynamoid/associations.rb

@@ -1,16 +1,21 @@
+# encoding: utf-8
 require 'dynamoid/associations/association'
 require 'dynamoid/associations/has_many'
 require 'dynamoid/associations/belongs_to'
 require 'dynamoid/associations/has_one'
 require 'dynamoid/associations/has_and_belongs_to_many'
 
-# encoding: utf-8
-module Dynamoid #:nodoc:
+module Dynamoid
 
-  # Connects models together through the magic of associations.
+  # Connects models together through the magic of associations. We enjoy four different kinds of associations presently:
+  #   * belongs_to
+  #   * has_and_belongs_to_many
+  #   * has_many
+  #   * has_one
   module Associations
     extend ActiveSupport::Concern
     
+    # Create the association tracking attribute and initialize it to an empty hash.
     included do
       class_attribute :associations
       
@@ -18,24 +23,68 @@ module Dynamoid #:nodoc:
     end
 
     module ClassMethods
+      
+      # create 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
+      # @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 [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
       def has_many(name, options = {})
         association(:has_many, name, options)
       end
       
+      # create a has_one association for this document.
+      #
+      # @param [Symbol] name the name of the association
+      # @param [Hash] options 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 [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
       def has_one(name, options = {})
         association(:has_one, name, options)
       end
       
+      # create a belongs_to association for this document.
+      #
+      # @param [Symbol] name the name of the association
+      # @param [Hash] options 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 [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
+      #
+      # @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.
+      #
+      # @param [Symbol] name the name of the association
+      # @param [Hash] options 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 [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
       def has_and_belongs_to_many(name, options = {})
         association(:has_and_belongs_to_many, name, options)
       end
       
       private
-      
+
+      # 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
+      #
+      # @since 0.2.0      
       def association(type, name, options = {})
         field "#{name}_ids".to_sym, :set
         self.associations[name] = options.merge(:type => type)

data/lib/dynamoid/associations/association.rb

@@ -1,12 +1,29 @@
 # encoding: utf-8
 module Dynamoid #:nodoc:
 
-  # The base association module.
+  # 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.
   module Associations
     module Association
       attr_accessor :name, :options, :source, :query
       include Enumerable
 
+      # Delegate methods to the records the association represents.
+      delegate :first, :last, :empty?, :size, :to => :records
+
+      # Create a new association.
+      # 
+      # @param [Class] source the source record of the association; that is, the record that you already have
+      # @param [Symbol] name the name of the association
+      # @param [Hash] options optional parameters for the association
+      # @option options [Class] :class the target class of the association; that is, the class to which the association objects belong
+      # @option options [Symbol] :class_name the name of the target class of the association; only this or Class is necessary
+      # @option options [Symbol] :inverse_of the name of the association on the target class
+      #
+      # @return [Dynamoid::Association] the actual association instance itself
+      #
+      # @since 0.2.0
       def initialize(source, name, options)
         @name = name
         @options = options
@@ -14,62 +31,148 @@ module Dynamoid #:nodoc:
         @query = {}
       end
       
-      def records
-        results = target_class.find(source_ids.to_a)
-        results = results.nil? ? [] : Array(results)
-        return results if query.empty?
-        results_with_query(results)
-      end
-      alias :all :records
-      
-      def empty?
-        records.empty?
-      end
+      # Alias convenience methods for the associations.
       alias :nil? :empty?
+      alias :count :size
       
-      def size
-        records.count
+      # The records associated to the source.
+      # 
+      # @return the association records; depending on which association this is, either a single instance or an array
+      #
+      # @since 0.2.0
+      def records
+        results = Array(target_class.find(source_ids.to_a))
+
+        if query.empty?
+          results
+        else
+          results_with_query(results)
+        end
       end
-      alias :count :size
+      alias :all :records
       
+      # Delegate include? to the records.
       def include?(object)
         records.include?(object)
       end
       
+      # @todo Improve the two methods below to not have quite so much duplicated code.
+      
+      # 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.
+      # 
+      # @param [Dynamoid::Document] object the object (or array of objects) to remove from the association
+      #
+      # @return [Dynamoid::Document] the deleted object
+      #
+      # @since 0.2.0
       def delete(object)
         source.update_attribute(source_attribute, source_ids - Array(object).collect(&:id))
         Array(object).collect{|o| self.send(:disassociate_target, o)} if target_association
         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.
+      # 
+      # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
+      #
+      # @return [Dynamoid::Document] the added object
+      #
+      # @since 0.2.0      
       def <<(object)
         source.update_attribute(source_attribute, source_ids.merge(Array(object).collect(&:id)))
         Array(object).collect{|o| self.send(:associate_target, o)} if target_association
         object
       end
-      
+
+      # Replace an association with object or array of objects. This removes all of the existing associated records and replaces them with
+      # the passed object(s), and associates the target association if it is detected to exist.
+      # 
+      # @param [Dynamoid::Document] object the object (or array of objects) to add to the association
+      #
+      # @return [Dynamoid::Document] the added object
+      #
+      # @since 0.2.0            
       def setter(object)
-        source.update_attribute(source_attribute, Array(object).collect(&:id))
-        Array(object).collect{|o| self.send(:associate_target, o)} if target_association
+        records.each {|o| delete(o)}
+        self << (object)
         object
       end
       
+      # Create a new instance of the target class and add it directly to the association.
+      # 
+      # @param [Hash] attribute hash for the new object
+      #
+      # @return [Dynamoid::Document] the newly-created object
+      #
+      # @since 0.2.0            
       def create(attributes = {})
-        object = target_class.create(attributes)
-        self << object
+        self << target_class.create(attributes)
+      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.
+      # 
+      # @param [Hash] attribute hash for the new object
+      #
+      # @return [Dynamoid::Document] the newly-created object
+      #
+      # @since 0.2.0            
+      def create!(attributes = {})
+        self << target_class.create!(attributes)
       end
       
+      
+      # Naive association filtering.
+      # 
+      # @param [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)
         args.each {|k, v| query[k] = v}
         self
       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.
+      # 
+      # @param [Hash] attribute hash for the new object
+      #
+      # @return [Dynamoid::Document] the newly-created object
+      #
+      # @since 0.2.0            
       def each(&block)
         records.each(&block)
       end
+
+      # Destroys all members of the association and removes them from the association.
+      # 
+      # @since 0.2.0
+      def destroy_all
+        objs = records
+        source.update_attribute(source_attribute, nil)
+        objs.each(&:destroy)
+      end
+
+      # Deletes all members of the association and removes them from the association.
+      # 
+      # @since 0.2.0
+      def delete_all
+        objs = records
+        source.update_attribute(source_attribute, nil)
+        objs.each(&:delete)
+      end
       
       private
       
+      # If a query exists, filter all existing results based on that query.
+      #
+      # @param [Array] results the raw results for the association
+      #
+      # @return [Array] the filtered results for the query
+      # 
+      # @since 0.2.0
       def results_with_query(results)
         results.find_all do |result|
           query.all? do |attribute, value|
@@ -77,27 +180,52 @@ module Dynamoid #:nodoc:
           end
         end
       end
-      
+
+      # The target class name, either inferred through the association's name or specified in options.
+      #
+      # @since 0.2.0
+      def target_class_name
+        options[:class_name] || name.to_s.classify
+      end
+
+      # The target class, either inferred through the association's name or specified in options.
+      #
+      # @since 0.2.0
       def target_class
-        name.to_s.singularize.capitalize.constantize
+        options[:class] || target_class_name.constantize
       end
       
+      # The target attribute: that is, the attribute on each object of the association that should reference the source.
+      #
+      # @since 0.2.0
       def target_attribute
         "#{target_association}_ids".to_sym if target_association
       end
-      
+
+      # The ids in the target association.
+      #
+      # @since 0.2.0      
       def target_ids
         target.send(target_attribute) || Set.new
       end
-      
+
+      # The ids in the target association.
+      #
+      # @since 0.2.0            
       def source_class
         source.class
       end
       
+      # The source's association attribute: the name of the association with _ids afterwards, like "users_ids".
+      #
+      # @since 0.2.0
       def source_attribute
         "#{name}_ids".to_sym
       end
       
+      # The ids in the source association.
+      #
+      # @since 0.2.0
       def source_ids
         source.send(source_attribute) || Set.new
       end
@@ -105,4 +233,4 @@ module Dynamoid #:nodoc:
     end
   end
   
-end
+end