openlogic-couchrest_model 1.0.0

data/lib/couchrest/model/design_doc.rb

@@ -0,0 +1,128 @@
+# encoding: utf-8
+module CouchRest
+  module Model
+    module DesignDoc
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        def design_doc
+          @design_doc ||= if auto_update_design_doc
+                            ::CouchRest::Design.new(default_design_doc)
+                          else
+                            stored_design_doc || ::CouchRest::Design.new(default_design_doc)
+                          end
+        end
+
+        def design_doc_id
+          "_design/#{design_doc_slug}"
+        end
+
+        def design_doc_slug
+          self.to_s
+        end
+
+        def design_doc_uri(db = database)
+          "#{db.root}/#{design_doc_id}"
+        end
+
+        # Retreive the latest version of the design document directly
+        # from the database. This is never cached and will return nil if
+        # the design is not present.
+        #
+        # Use this method if you'd like to compare revisions [_rev] which
+        # is not stored in the normal design doc.
+        def stored_design_doc(db = database)
+          db.get(design_doc_id)
+        rescue RestClient::ResourceNotFound
+          nil
+        end
+
+        # Save the design doc onto a target database in a thread-safe way,
+        # not modifying the model's design_doc
+        #
+        # See also save_design_doc! to always save the design doc even if there
+        # are no changes.
+        def save_design_doc(db = database, force = false)
+          update_design_doc(db, force)
+        end
+
+        # Force the update of the model's design_doc even if it hasn't changed.
+        def save_design_doc!(db = database)
+          save_design_doc(db, true)
+        end
+
+        private
+
+        def design_doc_cache
+          Thread.current[:couchrest_design_cache] ||= {}
+        end
+        def design_doc_cache_checksum(db)
+          design_doc_cache[design_doc_uri(db)]
+        end
+        def set_design_doc_cache_checksum(db, checksum)
+          design_doc_cache[design_doc_uri(db)] = checksum
+        end
+
+        # Writes out a design_doc to a given database if forced
+        # or the stored checksum is not the same as the current
+        # generated checksum.
+        #
+        # Returns the original design_doc provided, but does 
+        # not update it with the revision.
+        def update_design_doc(db, force = false)
+          return design_doc unless force || auto_update_design_doc
+
+          # Grab the design doc's checksum
+          checksum = design_doc.checksum!
+
+          # If auto updates enabled, check checksum cache
+          return design_doc if auto_update_design_doc && design_doc_cache_checksum(db) == checksum
+
+          retries = 1
+          begin
+            # Load up the stored doc (if present), update, and save
+            saved = stored_design_doc(db)
+            if saved
+              if force || saved['couchrest-hash'] != checksum
+                saved.merge!(design_doc)
+                db.save_doc(saved)
+                @design_doc = saved  # update memo to point to the document we actually saved
+              end
+            else
+              design_doc.delete('_rev') # This is a new document and so doesn't have a revision yet
+              db.save_doc(design_doc)
+            end
+          rescue RestClient::Conflict
+            # if we get a conflict retry the operation...
+            raise if retries < 1
+            retries -= 1
+            retry
+          end
+
+          # Ensure checksum cached for next attempt if using auto updates
+          set_design_doc_cache_checksum(db, checksum) if auto_update_design_doc
+          design_doc
+        end
+
+        def default_design_doc
+          {
+            "_id" => design_doc_id,
+            "language" => "javascript",
+            "views" => {
+              'all' => {
+                'map' => "function(doc) {
+                  if (doc['#{self.model_type_key}'] == '#{self.to_s}') {
+                    emit(doc['_id'],1);
+                  }
+                }"
+              }
+            }
+          }
+        end
+
+      end # module ClassMethods
+
+    end
+  end
+end

data/lib/couchrest/model/designs.rb

@@ -0,0 +1,91 @@
+
+#### 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?
+        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
+
+        # Generate a method that will provide a new View instance when
+        # requested.  This will also define the view in CouchDB unless
+        # auto_update_design_doc is disabled.
+        def view(name, opts = {})
+          View.create(model, name, opts) if model.auto_update_design_doc
+          create_view_method(name)
+        end
+
+        # Really simple design function that allows a filter
+        # to be added. Filters are simple functions used when listening
+        # to the _changes feed.
+        #
+        # No methods are created here, the design is simply updated.
+        # See the CouchDB API for more information on how to use this.
+        def filter(name, function)
+          filters = (self.model.design_doc['filters'] ||= {})
+          filters[name.to_s] = function
+        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/designs/view.rb

@@ -0,0 +1,513 @@
+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    = { }
+          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
+
+        # Return the number of documents in the currently defined result set.
+        # Use <tt>#count</tt> for the total number of documents regardless
+        # of the current limit defined.
+        def length
+          docs.length
+        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.skip(0).limit(1).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 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[:keys].nil? && 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? && query[:keys].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? && query[:keys].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
+
+        # Keys is a special CouchDB option that will cause the view request to be POSTed
+        # including an array of keys. Only documents with the matching keys will be 
+        # returned. This is much faster than sending multiple requests for a set 
+        # non-consecutive documents.
+        #
+        # If no values are provided, this method will act as a wrapper around 
+        # the rows result set, providing an array of keys.
+        def keys(*keys)
+          if keys.empty?
+            rows.map{|r| r.key}
+          else
+            raise "View#keys cannot by used when key or startkey/endkey have been set" unless query[:key].nil? && query[:startkey].nil? && query[:endkey].nil?
+            update_query(:keys => keys.first)
+          end
+        end
+
+
+        # The results should be provided in descending order. If the startkey or
+        # endkey query options have already been seen set, calling this method
+        # will automatically swap the options around. If you don't want this,
+        # simply set descending before any other option.
+        #
+        # Descending is false by default, and this method cannot
+        # be undone once used, it has no inverse option.
+        def descending
+          if query[:startkey] || query[:endkey]
+            query[:startkey], query[:endkey] = query[:endkey], query[:startkey]
+          elsif query[:startkey_docid] || query[:endkey_docid]
+            query[:startkey_docid], query[:endkey_docid] = query[:endkey_docid], query[:startkey_docid]
+          end
+          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?
+
+          # Remove the reduce value if its not needed to prevent CouchDB errors
+          query.delete(:reduce) unless can_reduce?
+
+          model.save_design_doc(use_database)
+
+          self.result = model.design_doc.view_on(use_database, name, query.reject{|k,v| v.nil?})
+        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 interpreted 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.
+          #
+          # By default, a check is made on each of the view's keys to ensure they
+          # do not contain a nil value ('null' in javascript). This is probably what
+          # you want in most cases but sometimes in can be useful to create an
+          # index where nil is permited. Set the <tt>:allow_nil</tt> option to true to
+          # remove this check.
+          #
+          # Conversely, keys are not checked to see if they are empty or blank. If you'd
+          # like to enable this, set the <tt>:allow_blank</tt> option to false. The default
+          # is true, empty strings are permited in the indexes.
+          #
+          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[:allow_blank] = opts[:allow_blank].nil? ? true : opts[:allow_blank]
+              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)"} unless opts[:allow_nil]
+              opts[:guards] += keys.map{|k| "(#{k} != '')"} unless opts[:allow_blank]
+              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