couchrest_model 1.0.0 → 1.1.0.beta

data/lib/couchrest/model/designs/view.rb

@@ -0,0 +1,486 @@
+module CouchRest
+  module Model
+    module Designs
+
+      #
+      # A proxy class that allows view queries to be created using
+      # chained method calls. After each call a new instance of the method
+      # is created based on the original in a similar fashion to ruby's Sequel 
+      # library, or Rails 3's Arel.
+      #
+      # CouchDB views have inherent limitations, so joins and filters as used in 
+      # a normal relational database are not possible.
+      #
+      class View
+        include Enumerable
+
+        attr_accessor :owner, :model, :name, :query, :result
+
+        # Initialize a new View object. This method should not be called from
+        # outside CouchRest Model.
+        def initialize(parent, new_query = {}, name = nil)
+          if parent.is_a?(Class) && parent < CouchRest::Model::Base
+            raise "Name must be provided for view to be initialized" if name.nil?
+            self.model    = parent
+            self.owner    = parent
+            self.name     = name.to_s
+            # Default options:
+            self.query    = { :reduce => false }
+          elsif parent.is_a?(self.class)
+            self.model    = (new_query.delete(:proxy) || parent.model)
+            self.owner    = parent.owner
+            self.name     = parent.name
+            self.query    = parent.query.dup
+          else
+            raise "View cannot be initialized without a parent Model or View"
+          end
+          query.update(new_query)
+          super()
+        end
+
+
+        # == View Execution Methods
+        #
+        # Request to the CouchDB database using the current query values.
+       
+        # Return each row wrapped in a ViewRow object. Unlike the raw
+        # CouchDB request, this will provide an empty array if there
+        # are no results.
+        def rows
+          return @rows if @rows
+          if execute && result['rows']
+            @rows ||= result['rows'].map{|v| ViewRow.new(v, model)}
+          else 
+            [ ]
+          end
+        end
+
+        # Fetch all the documents the view can access. If the view has
+        # not already been prepared for including documents in the query,
+        # it will be added automatically and reset any previously cached
+        # results.
+        def all
+          include_docs!
+          docs
+        end
+
+        # Provide all the documents from the view. If the view has not been
+        # prepared with the +include_docs+ option, each document will be 
+        # loaded individually.
+        def docs
+          @docs ||= rows.map{|r| r.doc}
+        end
+
+        # If another request has been made on the view, this will return 
+        # the first document in the set. If not, a new query object will be
+        # generated with a limit of 1 so that only the first document is 
+        # loaded.
+        def first
+          result ? all.first : limit(1).all.first
+        end
+
+        # Same as first but will order the view in descending order. This
+        # does not however reverse the search keys or the offset, so if you 
+        # are using a +startkey+ and +endkey+ you might end up with 
+        # unexpected results.
+        #
+        # If in doubt, don't use this method!
+        #
+        def last
+          result ? all.last : limit(1).descending.all.last
+        end
+
+        # Perform a count operation based on the current view. If the view
+        # can be reduced, the reduce will be performed and return the first
+        # value. This is okay for most simple queries, but may provide
+        # unexpected results if your reduce method does not calculate
+        # the total number of documents in a result set.
+        #
+        # Trying to use this method with the group option will raise an error.
+        #
+        # If no reduce function is defined, a query will be performed 
+        # to return the total number of rows, this is the equivalant of:
+        #
+        #    view.limit(0).total_rows
+        #
+        def count
+          raise "View#count cannot be used with group options" if query[:group]
+          if can_reduce?
+            row = reduce.rows.first
+            row.nil? ? 0 : row.value
+          else
+            limit(0).total_rows
+          end
+        end
+
+        # Check to see if the array of documents is empty. This *will* 
+        # perform the query and return all documents ready to use, if you don't
+        # want to load anything, use +#total_rows+ or +#count+ instead.
+        def empty?
+          all.empty?
+        end
+
+        # Run through each document provided by the +#all+ method.
+        # This is also used by the Enumerator mixin to provide all the standard
+        # ruby collection directly on the view.
+        def each(&block)
+          all.each(&block)
+        end
+
+        # Wrapper for the results offset. As per the CouchDB API,
+        # this may be nil if groups are used.
+        def offset
+          execute['offset']
+        end
+
+        # Wrapper for the total_rows value provided by the query. As per the
+        # CouchDB API, this may be nil if groups are used.
+        def total_rows
+          execute['total_rows']
+        end
+
+        # Convenience wrapper around the rows result set. This will provide
+        # and array of keys.
+        def keys
+          rows.map{|r| r.key}
+        end
+
+        # Convenience wrapper to provide all the values from the route
+        # set without having to go through +rows+.
+        def values
+          rows.map{|r| r.value}
+        end
+
+        # Accept requests as if the view was an array. Used for backwards compatibity
+        # with older queries:
+        #
+        #    Model.all(:raw => true, :limit => 0)['total_rows']
+        #
+        # In this example, the raw option will be ignored, and the total rows
+        # will still be accessible.
+        # 
+        def [](value)
+          execute[value]
+        end
+
+        # No yet implemented. Eventually this will provide a raw hash
+        # of the information CouchDB holds about the view.
+        def info
+          raise "Not yet implemented"
+        end
+
+
+        # == View Filter Methods
+        # 
+        # View filters return a copy of the view instance with the query 
+        # modified appropriatly. Errors will be raised if the methods
+        # are combined in an incorrect fashion.
+        #
+
+        # Find all entries in the index whose key matches the value provided.
+        #
+        # Cannot be used when the +#startkey+ or +#endkey+ have been set.
+        def key(value)
+          raise "View#key cannot be used when startkey or endkey have been set" unless query[:startkey].nil? && query[:endkey].nil?
+          update_query(:key => value)
+        end
+
+        # Find all index keys that start with the value provided. May or may 
+        # not be used in conjunction with the +endkey+ option.
+        #
+        # When the +#descending+ option is used (not the default), the start 
+        # and end keys should be reversed, as per the CouchDB API.
+        #
+        # Cannot be used if the key has been set.
+        def startkey(value)
+          raise "View#startkey cannot be used when key has been set" unless query[:key].nil?
+          update_query(:startkey => value)
+        end
+
+        # The result set should start from the position of the provided document. 
+        # The value may be provided as an object that responds to the +#id+ call
+        # or a string.
+        def startkey_doc(value)
+          update_query(:startkey_docid => value.is_a?(String) ? value : value.id)
+        end
+
+        # The opposite of +#startkey+, finds all index entries whose key is before
+        # the value specified.
+        #
+        # See the +#startkey+ method for more details and the +#inclusive_end+
+        # option.
+        def endkey(value)
+          raise "View#endkey cannot be used when key has been set" unless query[:key].nil?
+          update_query(:endkey => value)
+        end
+
+        # The result set should end at the position of the provided document. 
+        # The value may be provided as an object that responds to the +#id+ 
+        # call or a string.
+        def endkey_doc(value)
+          update_query(:endkey_docid => value.is_a?(String) ? value : value.id)
+        end
+
+
+        # The results should be provided in descending order.
+        #
+        # Descending is false by default, this method will enable it and cannot
+        # be undone.
+        def descending
+          update_query(:descending => true)
+        end
+
+        # Limit the result set to the value supplied.
+        def limit(value)
+          update_query(:limit => value)
+        end
+
+        # Skip the number of entries in the index specified by value. This would be
+        # the equivilent of an offset in SQL.
+        #
+        # The CouchDB documentation states that the skip option should not be used
+        # with large data sets as it is inefficient. Use the +startkey_doc+ method
+        # instead to skip ranges efficiently.
+        def skip(value = 0)
+          update_query(:skip => value)
+        end
+
+        # Use the reduce function on the view. If none is available this method
+        # will fail. 
+        def reduce
+          raise "Cannot reduce a view without a reduce method" unless can_reduce?
+          update_query(:reduce => true, :include_docs => nil)
+        end
+
+        # Control whether the reduce function reduces to a set of distinct keys
+        # or to a single result row.
+        #
+        # By default the value is false, and can only be set when the view's 
+        # +#reduce+ option has been set.
+        def group
+          raise "View#reduce must have been set before grouping is permitted" unless query[:reduce]
+          update_query(:group => true)
+        end
+
+        # Will set the level the grouping should be performed to. As per the 
+        # CouchDB API, it only makes sense when the index key is an array.
+        # 
+        # This will automatically set the group option.
+        def group_level(value)
+          group.update_query(:group_level => value.to_i)
+        end
+
+        def include_docs
+          update_query.include_docs!
+        end
+
+        ### Special View Filter Methods
+
+        # Specify the database the view should use. If not defined,
+        # an attempt will be made to load its value from the model.
+        def database(value)
+          update_query(:database => value)
+        end
+
+        # Set the view's proxy that will be used instead of the model
+        # for any future searches. As soon as this enters the
+        # new object's initializer it will be removed and replace
+        # the model object.
+        #
+        # See the Proxyable mixin for more details.
+        #
+        def proxy(value)
+          update_query(:proxy => value)
+        end
+
+        # Return any cached values to their nil state so that any queries
+        # requested later will have a fresh set of data.
+        def reset!
+          self.result = nil
+          @rows = nil
+          @docs = nil
+        end
+
+        # == Kaminari compatible pagination support
+        #
+        # Based on the really simple support for scoped pagination in the
+        # the Kaminari gem, we provide compatible methods here to perform
+        # the same actions you'd expect.
+        #
+
+        def page(page)
+          limit(owner.default_per_page).skip(owner.default_per_page * ([page.to_i, 1].max - 1))
+        end
+
+        def per(num)
+          raise "View#page must be called before #per!" if limit_value.nil? || offset_value.nil?
+          if (n = num.to_i) <= 0
+            self
+          else
+            limit(num).skip(offset_value / limit_value * n)
+          end
+        end
+
+        def total_count
+          @total_count ||= limit(nil).skip(nil).count
+        end
+
+        def offset_value
+          query[:skip]
+        end
+
+        def limit_value
+          query[:limit]
+        end
+
+        def num_pages
+          (total_count.to_f / limit_value).ceil
+        end
+
+        def current_page
+          (offset_value / limit_value) + 1
+        end
+
+
+
+        protected
+
+        def include_docs!
+          raise "Cannot include documents in view that has been reduced!" if query[:reduce]
+          reset! if result && !include_docs?
+          query[:include_docs] = true
+          self
+        end
+
+        def include_docs?
+          !!query[:include_docs]
+        end
+
+        def update_query(new_query = {})
+          self.class.new(self, new_query)
+        end
+
+        def design_doc
+          model.design_doc
+        end
+
+        def can_reduce?
+          !design_doc['views'][name]['reduce'].blank?
+        end
+
+        def use_database
+          query[:database] || model.database
+        end
+        
+        def execute
+          return self.result if result
+          raise "Database must be defined in model or view!" if use_database.nil?
+          retryable = true
+          # Remove the reduce value if its not needed
+          query.delete(:reduce) unless can_reduce?
+          begin
+            self.result = model.design_doc.view_on(use_database, name, query.reject{|k,v| v.nil?})
+          rescue RestClient::ResourceNotFound => e
+            if retryable
+              model.save_design_doc(use_database)
+              retryable = false
+              retry
+            else
+              raise e
+            end
+          end
+        end
+
+        # Class Methods
+        class << self
+          
+          # Simplified view creation. A new view will be added to the 
+          # provided model's design document using the name and options.
+          #
+          # If the view name starts with "by_" and +:by+ is not provided in 
+          # the options, the new view's map method will be interpretted and
+          # generated automatically. For example:
+          #
+          #   View.create(Meeting, "by_date_and_name")
+          #
+          # Will create a view that searches by the date and name properties. 
+          # Explicity setting the attributes to use is possible using the 
+          # +:by+ option. For example:
+          #
+          #   View.create(Meeting, "by_date_and_name", :by => [:date, :firstname, :lastname])
+          #
+          # The view name is the same, but three keys would be used in the
+          # subsecuent index.
+          #
+          def create(model, name, opts = {})
+
+            unless opts[:map]
+              if opts[:by].nil? && name.to_s =~ /^by_(.+)/
+                opts[:by] = $1.split(/_and_/)
+              end
+
+              raise "View cannot be created without recognised name, :map or :by options" if opts[:by].nil?
+
+              opts[:guards] ||= []
+              opts[:guards].push "(doc['#{model.model_type_key}'] == '#{model.to_s}')"
+
+              keys = opts[:by].map{|o| "doc['#{o}']"}
+              emit = keys.length == 1 ? keys.first : "[#{keys.join(', ')}]"
+              opts[:guards] += keys.map{|k| "(#{k} != null)"}
+              opts[:map] = <<-EOF
+                function(doc) {
+                  if (#{opts[:guards].join(' && ')}) {
+                    emit(#{emit}, 1);
+                  }
+                }
+              EOF
+              opts[:reduce] = <<-EOF
+                function(key, values, rereduce) {
+                  return sum(values);
+                }
+              EOF
+            end
+
+            model.design_doc['views'] ||= {}
+            view = model.design_doc['views'][name.to_s] = { }
+            view['map'] = opts[:map]
+            view['reduce'] = opts[:reduce] if opts[:reduce]
+            view
+          end
+
+        end
+
+      end
+
+      # A special wrapper class that provides easy access to the key
+      # fields in a result row.
+      class ViewRow < Hash
+        attr_reader :model
+        def initialize(hash, model)
+          @model    = model
+          replace(hash)
+        end
+        def id
+          self["id"]
+        end
+        def key
+          self["key"]
+        end
+        def value
+          self['value']
+        end
+        def raw_doc
+          self['doc']
+        end
+        # Send a request for the linked document either using the "id" field's
+        # value, or the ["value"]["_id"] used for linked documents.
+        def doc
+          return model.build_from_database(self['doc']) if self['doc']
+          doc_id = (value.is_a?(Hash) && value['_id']) ? value['_id'] : self.id
+          doc_id ? model.get(doc_id) : nil
+        end
+      end
+
+    end
+  end
+end

data/lib/couchrest/model/designs.rb

@@ -0,0 +1,81 @@
+
+#### NOTE Work in progress! Not yet used!
+
+module CouchRest
+  module Model
+
+    # A design block in CouchRest Model groups together the functionality of CouchDB's
+    # design documents in a simple block definition.
+    #
+    #   class Person < CouchRest::Model::Base
+    #     property :name
+    #     timestamps!
+    #
+    #     design do
+    #       view :by_name
+    #     end
+    #   end
+    #
+    module Designs
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        # Add views and other design document features
+        # to the current model.
+        def design(*args, &block)
+          mapper = DesignMapper.new(self)
+          mapper.create_view_method(:all)
+
+          mapper.instance_eval(&block) if block_given?
+
+          req_design_doc_refresh
+        end
+
+        # Override the default page pagination value:
+        #
+        #   class Person < CouchRest::Model::Base
+        #     paginates_per 10
+        #   end
+        #
+        def paginates_per(val)
+          @_default_per_page = val
+        end
+
+        # The models number of documents to return
+        # by default when performing pagination.
+        # Returns 25 unless explicitly overridden via <tt>paginates_per</tt>
+        def default_per_page
+          @_default_per_page || 25
+        end
+
+      end
+
+      # 
+      class DesignMapper
+
+        attr_accessor :model
+
+        def initialize(model)
+          self.model = model
+        end
+
+        # Define a view and generate a method that will provide a new 
+        # View instance when requested.
+        def view(name, opts = {})
+          View.create(model, name, opts)
+          create_view_method(name)
+        end
+
+        def create_view_method(name)
+          model.class_eval <<-EOS, __FILE__, __LINE__ + 1
+            def self.#{name}(opts = {})
+              CouchRest::Model::Designs::View.new(self, opts, '#{name}')
+            end
+          EOS
+        end
+
+      end
+    end
+  end
+end

data/lib/couchrest/model/document_queries.rb

@@ -88,7 +88,7 @@ module CouchRest
         def get!(id, db = database)
           raise "Missing or empty document ID" if id.to_s.empty?
           doc = db.get id
-          create_from_database(doc)
+          build_from_database(doc)
         end
         alias :find! :get!
         

data/lib/couchrest/model/persistence.rb

@@ -3,7 +3,7 @@ module CouchRest
     module Persistence
       extend ActiveSupport::Concern
 
-      # Create the document. Validation is enabled by default and will return 
+      # Create the document. Validation is enabled by default and will return
       # false if the document is not valid. If all goes well, the document will
       # be returned.
       def create(options = {})
@@ -16,13 +16,13 @@ module CouchRest
           end
         end
       end
-     
+
       # Creates the document in the db. Raises an exception
       # if the document is not created properly.
       def create!
         self.class.fail_validate!(self) unless self.create
       end
-      
+
       # Trigger the callbacks (before, after, around)
       # only if the document isn't new
       def update(options = {})
@@ -35,12 +35,12 @@ module CouchRest
           end
         end
       end
-      
+
       # Trigger the callbacks (before, after, around) and save the document
       def save(options = {})
         self.new? ? create(options) : update(options)
       end
-      
+
       # Saves the document to the db using save. Raises an exception
       # if the document is not saved properly.
       def save!
@@ -65,7 +65,6 @@ module CouchRest
       # Update the document's attributes and save. For example:
       #
       #   doc.update_attributes :name => "Fred"
-      # 
       # Is the equivilent of doing the following:
       #
       #   doc.attributes = { :name => "Fred" }
@@ -76,7 +75,17 @@ module CouchRest
         save
       end
 
-    protected
+      # Reloads the attributes of this object from the database.
+      # It doesn't override custom instance variables.
+      #
+      # Returns self.
+      def reload
+        merge!(self.class.get(id))
+        self
+      end
+
+
+      protected
 
       def perform_validations(options = {})
         perform_validation = case options
@@ -93,16 +102,16 @@ module CouchRest
 
         # Creates a new instance, bypassing attribute protection
         #
-        #
         # ==== Returns
         #  a document instance
-        def create_from_database(doc = {})
+        #
+        def build_from_database(doc = {})
           base = (doc[model_type_key].blank? || doc[model_type_key] == self.to_s) ? self : doc[model_type_key].constantize
-          base.new(doc, :directly_set_attributes => true)      
+          base.new(doc, :directly_set_attributes => true)
         end
 
-        # Defines an instance and save it directly to the database 
-        # 
+        # Defines an instance and save it directly to the database
+        #
         # ==== Returns
         #  returns the reloaded document
         def create(attributes = {})
@@ -110,9 +119,9 @@ module CouchRest
           instance.create
           instance
         end
-        
-        # Defines an instance and save it directly to the database 
-        # 
+
+        # Defines an instance and save it directly to the database
+        #
         # ==== Returns
         #  returns the reloaded document or raises an exception
         def create!(attributes = {})
@@ -148,7 +157,7 @@ module CouchRest
           raise Errors::Validations.new(document)
         end
       end
-      
+
 
     end
   end

data/lib/couchrest/model/properties.rb

@@ -156,7 +156,11 @@ module CouchRest
               type = Class.new(Hash) do
                 include CastedModel
               end
-              type.class_eval { yield type }
+              if block.arity == 1 # Traditional, with options
+                type.class_eval { yield type }
+              else
+                type.instance_exec(&block)
+              end
               type = [type] # inject as an array
             end
             property = Property.new(name, type, options)