georgepalmer-couch_foo 0.7.1

data/README.rdoc

@@ -0,0 +1,113 @@
+= CouchFoo
+
+== Overview
+
+CouchFoo provides an ActiveRecord styled interface to CouchDB.  The external API is nearly identical 
+to ActiveRecord so it should be possible to migrate your applications quite easily.  That said, there
+are a few minor differences to the way CouchDB works.  In particular:
+* CouchDB is schema free so property defintions for the document are defined in the model (like DataMapper)
+* :select, :joins, :having, :group, :from and :lock are not available on find or associations as they don't apply (locking is handled as conflict resolution at insertion time)
+* :conditions can only accept a hash and not an array or SQL.  For example :conditions => {:user_name => "Georgio_1999"}
+* :offset is less efficient in CouchDB - there's more on this in the rdoc
+* :order is applied after results are retrieved from the database.  Therefore :order cannot be used with :limit without a new option :use_key.  This is explained fully in the quick start guide and CouchFoo#find documentation
+* :include isn't implemented yet but the finders and associations still accept the option so you won't need to make any code changes
+* By default results are ordered by document key.  The key uses a UUID scheme so these don't auto-increment and are likely to come out in a different order to insertion.  default_sort can be used on a model to sort by create date by default and overcome this
+* validates_uniqueness_of has had the :case_sensitive option removed
+* Because there's no SQL there's no SQL finder methods
+* Timezones, aggregations and fixtures are not yet implemented
+* The price of index updating is paid when next accessing the index rather than the point of insertion.  This can be more efficient or less depending on your application.  It may make sense to use an external process to do the updating for you - see CouchFoo#find for more on this
+* On that note, occasional compacting of CouchDB is required to recover space from old versions of documents.  This can be kicked off in several ways (see quick start guide)
+
+It is recommend that you read the quick start and performance sections in the rdoc for a full overview of differences and points to be aware of when developing.
+
+
+== Getting started
+
+CouchFoo::Base.set_database("http://localhost:5984/opnli_dev", <yourcouchdbversion>)
+
+If using with Rails you will need to create an initializer to do this (until proper integration is added)
+
+
+== Examples of usage
+
+Basic operations are the same as ActiveRecord:
+  class Address < CouchFoo::Base
+    property :number, Integer
+    property :street, String
+    property :postcode # Any generic type is fine as long as .to_json can be called on it
+  end 
+
+  address1 = Address.create(:number => 3, :street => "My Street", :postcode => "secret") # Create address
+  address2 = Address.create(:number => 27, :street => "Another Street", :postcode => "secret")
+  Address.find.all # = [address1, address2] or maybe [address2, address2] depending on key generation
+  Address.first    # = address1 or address2 depending on keys so probably isn't as expected
+  Address.find_by_street("My Street") # = address1
+
+As key generation is through a UUID scheme, the order can't be predicted.  However you can order the
+results by default:
+  class Address < CouchFoo::Base
+    property :number, Integer
+    property :street, String
+    property :postcode # Any generic type is fine as long as .to_json can be called on it
+    property :created_at, DateTime
+    
+    default_sort :created_at
+  end
+  
+  Address.find.all # = [address1, address2]
+  Address.first    # = address1 or address2, sorting is applied after results
+  Address.first(:use_key => :created_at) # = address1 but at the price of creating a new index
+
+Conditions work slightly differently:
+  Address.find(:all, :conditions {:street => "My Street"}) # = address1, creates index on :street
+  Address.find(:all, :conditions {:created_at => "sometime"}) # Uses same index as :use_key => :created_at
+  Address.find(:all, :use_key => :street, :startkey => 'p') # All streets from p in alphabet, reuses the index created 2 lines up
+
+As well as providing support for people using relational databases, CouchFoo attempts to provide a library for those wanting to use CouchDB as a document-orientated database:
+  class Document < CouchFoo::Base
+    property :number, Integer
+    property :street, String
+    
+    view :number_ordered, "function(doc) {emit([doc.number , doc.street], doc); }", nil, :descending => true
+  end
+
+  Document.number_ordered(:limit => 75) # Will get the last 75 documents in the database ordered by number, street attributes
+
+Associations work as expected but you must to remember to add the properties required for an association (we'll make this automatic soon):
+  class House < CouchFoo::Base
+  	has_many :windows
+  end
+  
+  class Window < CouchFoo::Base
+    property :house_id, String
+  	belongs_to :house
+  end
+
+
+== Credits
+
+This gem was inspired some excellent work on CouchPotato, CouchREST, ActiveCouch and RelaxDB gems.  Each offered
+its own benefits and own challenges.  After hacking with each I couldn't get a library was happy with.  So I
+started with ActiveRecord and modified it to work with CouchDB.  Some areas required more work than others but
+a lot of features were achieved for free once the base level of functionality had been achieved.  Credit to DHH,
+the rails core guys and the CouchDB gems that inspired this work. 
+
+
+== What's left to do?
+
+Please feel free to fork and hit me with a request to merge back in.  At the moment, the following areas need addressing:
+
+* Proper integration with rails using a couchdb.yml config file
+* Example ruby script for updating indexes as an external process, and the same for database compacting  
+* :include for database queries
+* Remove dependency from CouchRest?  Add support for attachments and log calls to server so know performance times.  General tidy up of database.rb
+* inline and HABTM inline associations.  Also x_id and x_type properties should be automatically defined
+* compatability with willpaginate and friends
+* cleanup of associations, reflection, validations classes (were modified in a rush)
+* has_many :through
+* Rest of calculations, timezones, aggregations and fixtures
+* Diff with AR to check got everything in
+* DataMapper interface
+* Tool to migrate DB from MySQL to CouchDB
+* some kind of generic admin interface where can just browse around data structure?
+* grep of code and doc for records and columns, should be documents and attributes

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 7
+:patch: 1

data/lib/boolean.rb

@@ -0,0 +1,3 @@
+class Boolean < TrueClass
+  
+end

data/lib/couch_foo/associations/association_collection.rb

@@ -0,0 +1,346 @@
+require 'set'
+
+module CouchFoo
+  module Associations
+    class AssociationCollection < AssociationProxy #:nodoc:
+      def initialize(owner, reflection)
+        super
+        construct_conditions
+      end
+      
+      def find(*args)
+        options = args.extract_options!
+        
+        options[:conditions] = @association_conditions.merge(options[:conditions] || {})
+        
+        # Multiple ordering not supported at the minute
+        #if options[:order] && @reflection.options[:order]
+        #  options[:order] = "#{options[:order]}, #{@reflection.options[:order]}"
+        #elsif @reflection.options[:order]
+        if @reflection.options[:order]
+          options[:order] = @reflection.options[:order]
+        end
+
+        # Build options specific to association
+        construct_find_options!(options)
+        
+        merge_options_from_reflection!(options)
+        
+        # Pass through args exactly as we received them.
+        args << options
+
+        @reflection.klass.find(*args)
+      end
+      
+      # Fetches the first element directly if it can
+      def first(*args)
+        if fetch_first_or_last_using_find? args
+          find(:first, *args)
+        else
+          load_target unless loaded?
+          @target.first(*args)
+        end
+      end
+
+      # Fetches the last element directly if it can
+      def last(*args)
+        if fetch_first_or_last_using_find? args
+          find(:last, *args)
+        else
+          load_target unless loaded?
+          @target.last(*args)
+        end
+      end
+
+      def to_ary
+        load_target
+        @target.to_ary
+      end
+
+      def reset
+        reset_target!
+        @loaded = false
+      end
+
+      def build(attributes = {}, &block)
+        if attributes.is_a?(Array)
+          attributes.collect { |attr| build(attr, &block) }
+        else
+          build_record(attributes) do |record|
+            block.call(record) if block_given?
+            set_belongs_to_association_for(record)
+          end
+        end
+      end
+
+      # Add +records+ to this association.  Returns +self+ so method calls may be chained.  
+      # Since << flattens its argument list and inserts each record, +push+ and +concat+ behave identically.
+      def <<(*records)
+        result = true
+        load_target if @owner.new_record?
+
+        @owner.transaction do
+          flatten_deeper(records).each do |record|
+            raise_on_type_mismatch(record)
+            add_record_to_target_with_callbacks(record) do |r|
+              result &&= insert_record(record) unless @owner.new_record?
+            end
+          end
+        end
+
+        result && self
+      end
+
+      alias_method :push, :<<
+      alias_method :concat, :<<
+
+      # Remove all records from this association
+      def delete_all
+        load_target
+        delete(@target)
+        reset_target!
+      end
+      
+      # Calculate sum
+      def sum(*args)
+        if block_given?
+          calculate(:sum, *args) { |*block_args| yield(*block_args) }
+        else
+          calculate(:sum, *args)
+        end
+      end
+
+      # Remove +records+ from this association.  Does not destroy +records+.
+      def delete(*records)
+        records = flatten_deeper(records)
+        records.each { |record| raise_on_type_mismatch(record) }
+        
+        @owner.transaction do
+          records.each { |record| callback(:before_remove, record) }
+          
+          old_records = records.reject {|r| r.new_record? }
+          delete_records(old_records) if old_records.any?
+          
+          records.each do |record|
+            @target.delete(record)
+            callback(:after_remove, record)
+          end
+        end
+      end
+
+      # Removes all records from this association.  Returns +self+ so method calls may be chained.
+      def clear
+        return self if length.zero? # forces load_target if it hasn't happened already
+
+        if @reflection.options[:dependent] && @reflection.options[:dependent] == :destroy
+          destroy_all
+        else          
+          delete_all
+        end
+
+        self
+      end
+      
+      def destroy_all
+        @owner.transaction do
+          each { |record| record.destroy }
+        end
+
+        reset_target!
+      end
+      
+      def create(attrs = {})
+        if attrs.is_a?(Array)
+          attrs.collect { |attr| create(attr) }
+        else
+          create_record(attrs) do |record|
+            yield(record) if block_given?
+            record.save
+          end
+        end
+      end
+
+      def create!(attrs = {})
+        create_record(attrs) do |record|
+          yield(record) if block_given?
+          record.save!
+        end
+      end
+
+      # Returns the size of the collection by executing a count query if the collection hasn't been 
+      # loaded and calling collection.size if it has.  If it's more likely than not that the 
+      # collection does have a size larger than zero and you need to fetch that collection afterwards, 
+      # it'll take one database query if you use length.
+      def size
+        if @owner.new_record? || (loaded? && !@reflection.options[:uniq])
+          @target.size
+        elsif !loaded? && !@reflection.options[:uniq] && @target.is_a?(Array)
+          unsaved_records = @target.select { |r| r.new_record? }
+          unsaved_records.size + count_records
+        else
+          count_records
+        end
+      end
+
+      # Returns the size of the collection by loading it and calling size on the array. If you want 
+      # to use this method to check whether the collection is empty, use collection.length.zero? 
+      # instead of collection.empty?
+      def length
+        load_target.size
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      def any?
+        if block_given?
+          method_missing(:any?) { |*block_args| yield(*block_args) }
+        else
+          !empty?
+        end
+      end
+
+      def uniq(collection = self)
+        seen = Set.new
+        collection.inject([]) do |kept, record|
+          unless seen.include?(record.id)
+            kept << record
+            seen << record.id
+          end
+          kept
+        end
+      end
+
+      # Replace this collection with +other_array+
+      # This will perform a diff and delete/add only records that have changed.
+      def replace(other_array)
+        other_array.each { |val| raise_on_type_mismatch(val) }
+
+        load_target
+        other   = other_array.size < 100 ? other_array : other_array.to_set
+        current = @target.size < 100 ? @target : @target.to_set
+
+        @owner.transaction do
+          delete(@target.select { |v| !other.include?(v) })
+          concat(other_array.select { |v| !current.include?(v) })
+        end
+      end
+
+      def include?(record)
+        return false unless record.is_a?(@reflection.klass)
+        load_target if !loaded?
+        return @target.include?(record) if loaded?
+        exists?(record)
+      end
+
+      protected
+        def construct_find_options!(options)
+        end
+        
+        def load_target
+          if !@owner.new_record? || foreign_key_present
+            begin
+              if !loaded?
+                if @target.is_a?(Array) && @target.any?
+                  @target = find_target + @target.find_all {|t| t.new_record? }
+                else
+                  @target = find_target
+                end
+              end
+            rescue CouchFoo::DocumentNotFound
+              reset
+            end
+          end
+
+          loaded if target
+          target
+        end
+        
+        def method_missing(method, *args)
+          if @target.respond_to?(method) || (!@reflection.klass.respond_to?(method) && Class.respond_to?(method))
+            if block_given?
+              super { |*block_args| yield(*block_args) }
+            else
+              super
+            end
+          elsif @reflection.klass.scopes.include?(method)
+            @reflection.klass.scopes[method].call(self, *args)
+          else          
+            with_scope(construct_scope) do
+              if block_given?
+                @reflection.klass.send(method, *args) { |*block_args| yield(*block_args) }
+              else
+                @reflection.klass.send(method, *args)
+              end
+            end
+          end
+        end
+
+        # overloaded in derived Association classes to provide useful scoping depending on association type.
+        def construct_scope
+          {}
+        end
+
+        def reset_target!
+          @target = Array.new
+        end
+
+        def find_target
+          @reflection.options[:uniq] ? uniq(records) : find(:all)
+        end
+
+      private
+        def create_record(attrs)
+          attrs.update(@reflection.options[:conditions]) if @reflection.options[:conditions].is_a?(Hash)
+          ensure_owner_is_not_new
+          record = @reflection.klass.send(:with_scope, :create => construct_scope[:create]) { @reflection.klass.new(attrs) }
+          if block_given?
+            add_record_to_target_with_callbacks(record) { |*block_args| yield(*block_args) }
+          else
+            add_record_to_target_with_callbacks(record)
+          end
+        end
+
+        def build_record(attrs)
+          attrs.update(@reflection.options[:conditions]) if @reflection.options[:conditions].is_a?(Hash)
+          record = @reflection.klass.new(attrs)
+          if block_given?
+            add_record_to_target_with_callbacks(record) { |*block_args| yield(*block_args) }
+          else
+            add_record_to_target_with_callbacks(record)
+          end
+        end
+
+        def add_record_to_target_with_callbacks(record)
+          callback(:before_add, record)
+          yield(record) if block_given?
+          @target ||= [] unless loaded?
+          @target << record unless @reflection.options[:uniq] && @target.include?(record)
+          callback(:after_add, record)
+          record
+        end
+
+        def callback(method, record)
+          callbacks_for(method).each do |callback|
+            ActiveSupport::Callbacks::Callback.new(method, callback, record).call(@owner, record)
+          end
+        end
+
+        def callbacks_for(callback_name)
+          full_callback_name = "#{callback_name}_for_#{@reflection.name}"
+          @owner.class.read_inheritable_attribute(full_callback_name.to_sym) || []
+        end   
+        
+        def ensure_owner_is_not_new
+          if @owner.new_record?
+            raise CouchFoo::DocumentNotSaved, "You cannot call create unless the parent is saved"
+          end
+        end
+
+        def fetch_first_or_last_using_find?(args)
+          args.first.kind_of?(Hash) || !(loaded? || @owner.new_record? || !@target.blank? || args.first.kind_of?(Integer))
+        end
+    end
+  end
+end

data/lib/couch_foo/associations/association_proxy.rb

@@ -0,0 +1,204 @@
+module CouchFoo
+  module Associations
+    # This is the root class of all association proxies:
+    #
+    #   AssociationProxy
+    #     BelongsToAssociation
+    #       HasOneAssociation
+    #     BelongsToPolymorphicAssociation
+    #     AssociationCollection
+    #       HasAndBelongsToManyAssociation
+    #       HasManyAssociation
+    #
+    # At there moment there are no Through associations
+    #
+    # Association proxies in Couch Foo are middlemen between the object that
+    # holds the association, known as the <tt>@owner</tt>, and the actual associated
+    # object, known as the <tt>@target</tt>. The kind of association any proxy is
+    # about is available in <tt>@reflection</tt>. That's an instance of the class
+    # CouchFoo::Reflection::AssociationReflection.
+    #
+    # For example, given
+    #
+    #   class Blog < CouchFoo::Base
+    #     has_many :posts
+    #   end
+    #
+    #   blog = Blog.find(:first)
+    #
+    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
+    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
+    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
+    #
+    # This class has most of the basic instance methods removed, and delegates
+    # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a
+    # corner case, it even removes the +class+ method and that's why you get
+    #
+    #   blog.posts.class # => Array
+    #
+    # though the object behind <tt>blog.posts</tt> is not an Array, but an
+    # CouchFoo::Associations::HasManyAssociation.
+    #
+    # The <tt>@target</tt> object is not loaded until needed. For example,
+    #
+    #   blog.posts.count
+    #
+    # is computed directly through a count view and does not trigger by itself the
+    # instantiation of the actual post records.
+    class AssociationProxy #:nodoc:
+      alias_method :proxy_respond_to?, :respond_to?
+      alias_method :proxy_extend, :extend
+      delegate :to_param, :to => :proxy_target
+      instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|proxy_|^object_id$)/ }
+
+      def initialize(owner, reflection)
+        @owner, @reflection = owner, reflection
+        Array(reflection.options[:extend]).each { |ext| proxy_extend(ext) }
+        reset
+      end
+
+      def proxy_owner
+        @owner
+      end
+
+      def proxy_reflection
+        @reflection
+      end
+
+      def proxy_target
+        @target
+      end
+
+      def respond_to?(*args)
+        proxy_respond_to?(*args) || (load_target && @target.respond_to?(*args))
+      end
+
+      # Explicitly proxy === because the instance method removal above
+      # doesn't catch it.
+      def ===(other)
+        load_target
+        other === @target
+      end
+
+      def conditions
+        @conditions ||= @reflection.options[:conditions]
+      end
+
+      def reset
+        @loaded = false
+        @target = nil
+      end
+
+      def reload
+        reset
+        load_target
+        self unless @target.nil?
+      end
+
+      def loaded?
+        @loaded
+      end
+
+      def loaded
+        @loaded = true
+      end
+
+      def target
+        @target
+      end
+
+      def target=(target)
+        @target = target
+        loaded
+      end
+
+      def inspect
+        load_target
+        @target.inspect
+      end
+
+      protected
+        def dependent?
+          @reflection.options[:dependent]
+        end
+
+        def quoted_record_ids(records)
+          records.map { |record| record.quoted_id }.join(',')
+        end
+
+        def set_belongs_to_association_for(record)
+          if @reflection.options[:as]
+            record["#{@reflection.options[:as]}_id".to_sym]   = @owner.id unless @owner.new_record?
+            record["#{@reflection.options[:as]}_type".to_sym] = @owner.class.name.to_s
+          else
+            record[@reflection.primary_key_name] = @owner.id unless @owner.new_record?
+          end
+        end
+
+        def merge_options_from_reflection!(options)
+          options.reverse_merge!(
+            :limit   => @reflection.options[:limit],
+            :offset  => @reflection.options[:offset],
+            :include => @reflection.options[:include],
+            :readonly  => @reflection.options[:readonly]
+          )
+        end
+
+        def with_scope(*args, &block)
+          @reflection.klass.send :with_scope, *args, &block
+        end
+
+      private
+        def method_missing(method, *args)
+          if load_target
+            if block_given?
+              @target.send(method, *args)  { |*block_args| yield(*block_args) }
+            else
+              @target.send(method, *args)
+            end
+          end
+        end
+
+        # Loads the target if needed and returns it.
+        #
+        # This method is abstract in the sense that it relies on +find_target+,
+        # which is expected to be provided by descendants.
+        #
+        # If the target is already loaded it is just returned. Thus, you can call
+        # +load_target+ unconditionally to get the target.
+        #
+        # CouchFoo::DocumentNotFound is rescued within the method, and it is
+        # not reraised. The proxy is reset and +nil+ is the return value.
+        def load_target
+          return nil unless defined?(@loaded)
+
+          if !loaded? and (!@owner.new_record? || foreign_key_present)
+            @target = find_target
+          end
+
+          @loaded = true
+          @target
+        rescue CouchFoo::DocumentNotFound
+          reset
+        end
+
+        # Can be overwritten by associations that might have the foreign key available for an association without
+        # having the object itself (and still being a new record). Currently, only belongs_to presents this scenario.
+        def foreign_key_present
+          false
+        end
+
+        def raise_on_type_mismatch(record)
+          unless record.is_a?(@reflection.klass)
+            message = "#{@reflection.class_name}(##{@reflection.klass.object_id}) expected, got #{record.class}(##{record.class.object_id})"
+            raise CouchFoo::AssociationTypeMismatch, message
+          end
+        end
+
+        # Array#flatten has problems with recursive arrays. Going one level deeper solves the majority of the problems.
+        def flatten_deeper(array)
+          array.collect { |element| element.respond_to?(:flatten) ? element.flatten : element }.flatten
+        end
+    end
+  end
+end