paulcarey-relaxdb 0.1.3 → 0.2.0

data/README.textile

@@ -1,3 +1,7 @@
+h3. What's New?
+ * Pagination! CouchDB offers great support for retrieving a subset of data, but the housekeeping is tricky. RelaxDB takes care of it.
+ * Works with CouchDB 0.9 trunk as of 2008/10/08. Note that pagination won't work on trunk unil https://issues.apache.org/jira/browse/COUCHDB-135 is fixed.
+
 h2. Overview
 
 RelaxDB provides a Ruby interface to CouchDB. It offers a simple idiom for specifying object relationships. The underlying objects are persisted to the mighty CouchDB. Combined with the schema free nature of CouchDB, RelaxDB's current strength lies in quick prototyping of object models.
@@ -64,6 +68,32 @@ h3. Exploring models
 </code>
 </pre>
 
+h3. Paginating
+
+<pre>
+<code>
+  # Controller (merb-action-args used for extracting view_params)
+
+  def action(view_params={})
+    u_id = @user._id
+
+    @posts = Post.paginate_by(view_params, :writer_id, :created_at) do |p|
+      p.startkey([u_id, {}]).endkey([u_id]).descending(true).count(5)
+    end
+    render
+  end
+  
+  # In your view
+  
+  <% @posts.each do |p| %>
+    <%= p.contents %>
+  <% end %>
+  
+  <%= link_to "prev", "/posts/?#{@posts.prev_query}" if @posts.prev_query %>
+  <%= link_to "next", "/posts/?#{@posts.next_query}" if @posts.next_query %>  
+</code>
+</pre>
+
 h3. Creating views by hand
 
 <pre>
@@ -87,6 +117,24 @@ h3. Creating views by hand
 </code>
 </pre>
 
+h3. Visualise
+
+Create an object graph by simply running
+<pre>
+<code>
+RelaxDB::GraphCreator.create
+</code>
+</pre>
+
+Requires graphviz. Useful for visualising relationships between a limited number of document e.g. test fixtures. "Description and example":http://dev.strawberrydiva.com/visually_explore_couchdb/.
+
+h3. Experimental Features
+
+* Declarative denormalisation
+** Create a partial object graph in JSON with a single call
+** May be used to require fewer GET requests
+** View the denormalisation spec for examples
+
 h2. Incomplete list of limitations
 
 * Error handling is not robust

data/Rakefile

@@ -4,7 +4,7 @@ require 'spec/rake/spectask'
 
 PLUGIN = "relaxdb"
 NAME = "relaxdb"
-GEM_VERSION = "0.1.3"
+GEM_VERSION = "0.2.0"
 AUTHOR = "Paul Carey"
 EMAIL = "paul.p.carey@gmail.com"
 HOMEPAGE = "http://github.com/paulcarey/relaxdb/"

data/lib/more/grapher.rb

@@ -1,5 +1,11 @@
 module RelaxDB
   
+  #
+  # The GraphCreator uses dot to create a graphical model of an entire CouchDB database
+  # It probably only makes sense to run it on a database of a limited size
+  # The created graphs can be very useful for exploring relationships
+  # Run ruby scratch/grapher_demo.rb for an example
+  #
   class GraphCreator
     
     def self.create

data/lib/relaxdb.rb

@@ -20,6 +20,8 @@ require 'relaxdb/document'
 require 'relaxdb/extlib'
 require 'relaxdb/has_many_proxy'
 require 'relaxdb/has_one_proxy'
+require 'relaxdb/paginate_params'
+require 'relaxdb/paginator'
 require 'relaxdb/query'
 require 'relaxdb/references_many_proxy'
 require 'relaxdb/relaxdb'
@@ -27,6 +29,7 @@ require 'relaxdb/server'
 require 'relaxdb/sorted_by_view'
 require 'relaxdb/uuid_generator'
 require 'relaxdb/view_object'
+require 'relaxdb/view_result'
 require 'relaxdb/view_uploader'
 require 'relaxdb/views'
 require 'more/grapher.rb'

data/lib/relaxdb/design_doc.rb

@@ -24,7 +24,7 @@ module RelaxDB
   
     def save
       database = RelaxDB.db    
-      resp = database.put("#{@data['_id']}", @data.to_json)
+      resp = database.put(::CGI::escape(@data["_id"]), @data.to_json)
       @data["_rev"] = JSON.parse(resp.body)["rev"]
       self
     end
@@ -32,7 +32,7 @@ module RelaxDB
     def self.get(client_class)
       begin
         database = RelaxDB.db
-        resp = database.get("_design/#{client_class}")
+        resp = database.get(::CGI::escape("_design/#{client_class}"))
         DesignDocument.new(client_class, JSON.parse(resp.body))
       rescue => e
         DesignDocument.new(client_class, {"_id" => "_design/#{client_class}"} )
@@ -41,7 +41,7 @@ module RelaxDB
     
     def destroy!
       # Implicitly prevent the object from being resaved by failing to update its revision
-      RelaxDB.db.delete("#{@data["_id"]}?rev=#{@data["_rev"]}")
+      RelaxDB.db.delete("#{::CGI::escape(@data["_id"])}?rev=#{@data["_rev"]}")
       self      
     end
   

data/lib/relaxdb/document.rb

@@ -278,6 +278,11 @@ module RelaxDB
       define_method("#{relationship}_id=") do |id|
         instance_variable_set("@#{relationship}_id".to_sym, id)
       end
+
+      # Allows belongs_to relationships to be used by the paginator
+      define_method("#{relationship}_id") do
+        instance_variable_get("@#{relationship}_id")
+      end
       
     end
     
@@ -346,7 +351,26 @@ module RelaxDB
         callback.is_a?(Proc) ? callback.call(self) : send(callback)
       end
     end
-            
+    
+    def self.paginate_by(page_params, *atts)
+      paginate_params = PaginateParams.new
+      yield paginate_params
+      raise paginate_params.error_msg if paginate_params.invalid? 
+      
+      paginator = Paginator.new(paginate_params, page_params)
+                  
+      doc_view = SortedByView.new(self.name, *atts)
+      doc_query = Query.new(self.name, doc_view.view_name)
+      doc_query.merge(paginator.paginate_params)
+      
+      @docs = RelaxDB.retrieve(doc_query.view_path, self, doc_view.view_name, doc_view.map_function)
+      @docs.reverse! if paginate_params.order_inverted?
+      
+      paginator.add_next_and_prev(@docs, self.name, doc_view, atts)
+      
+      @docs
+    end
+                
   end
   
 end

data/lib/relaxdb/paginate_params.rb

@@ -0,0 +1,52 @@
+module RelaxDB
+
+  class PaginateParams
+        
+    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending group)
+  
+    @@params.each do |param|
+      define_method(param.to_sym) do |*val|
+        if val.empty?
+          instance_variable_get("@#{param}")
+        else
+          instance_variable_set("@#{param}", val[0])
+          # null is meaningful to CouchDB. _set allows us to know that a param has been set, even to nil
+          instance_variable_set("@#{param}_set", true)
+          self
+        end
+      end
+    end
+    
+    def initialize
+      # If a client hasn't explicitly set descending, set it to the CouchDB default
+      @descending = false if @descending.nil?
+    end
+  
+    def update(params)
+      @order_inverted = params[:descending].nil? ? false : @descending ^ params[:descending]
+      @descending = !@descending if @order_inverted
+
+      @endkey = @startkey if @order_inverted
+    
+      @startkey = params[:startkey] || @startkey
+    
+      @skip = 1 if params[:startkey]
+      
+      @startkey_docid = params[:startkey_docid] if params[:startkey_docid]
+      @endkey_docid = params[:endkey_docid] if params[:endkey_docid]
+    end
+  
+    def order_inverted?
+      @order_inverted
+    end
+    
+    def invalid?
+      # Simply because allowing either to be omitted increases the complexity of the paginator
+      # This constraint may be removed in future, but don't hold your breath
+      @startkey_set && @endkey_set ? nil : "Both startkey and endkey must be set"
+    end
+    alias error_msg invalid?
+      
+  end
+
+end

data/lib/relaxdb/paginator.rb

@@ -0,0 +1,79 @@
+module RelaxDB  
+
+  class Paginator
+    
+    attr_reader :paginate_params
+
+    def initialize(paginate_params, page_params)
+      @paginate_params = paginate_params
+      @orig_paginate_params = @paginate_params.clone
+      
+      page_params = page_params.is_a?(String) ? JSON.parse(page_params).to_mash : page_params
+      @paginate_params.update(page_params)
+    end
+
+    def total_doc_count(design_doc, view)
+      query = lambda do
+        RelaxDB.view(design_doc, view.reduce_view_name) do |q|
+          q.group(true).group_level(0)
+          q.startkey(@orig_paginate_params.startkey).endkey(@orig_paginate_params.endkey).descending(@orig_paginate_params.descending)  
+        end
+      end
+      
+      begin
+        result = query.call
+      rescue
+        # add the map reduce func if it doesn't exist
+        DesignDocument.get(design_doc).add_map_view(view.reduce_view_name, view.map_function).
+          add_reduce_view(view.reduce_view_name, view.reduce_function).save
+        result = query.call
+      end        
+      
+      total_docs = RelaxDB.reduce_result(result)
+    end
+    
+    def add_next_and_prev(docs, design_doc, view, view_keys)
+      unless docs.empty?
+        no_docs = docs.size
+        offset = docs.offset
+        orig_offset = orig_offset(Query.new(design_doc, view.view_name), view)
+        total_doc_count = total_doc_count(design_doc, view)      
+      
+        next_key = view_keys.map { |a| docs.last.send(a) }
+        next_key = next_key.length == 1 ? next_key[0] : next_key
+        next_key_docid = docs.last._id
+        next_params = { :startkey => next_key, :startkey_docid => next_key_docid, :descending => @orig_paginate_params.descending }
+        next_exists = !@paginate_params.order_inverted? ? (offset - orig_offset + no_docs < total_doc_count) : true
+      
+        prev_key = view_keys.map { |a| docs.first.send(a) }
+        prev_key = prev_key.length == 1 ? prev_key[0] : prev_key
+        prev_key_docid = docs.first._id
+        prev_params = { :startkey => prev_key, :startkey_docid => prev_key_docid, :descending => !@orig_paginate_params.descending }
+        prev_exists = @paginate_params.order_inverted? ? (offset - orig_offset + no_docs < total_doc_count) : 
+          (offset - orig_offset == 0 ? false : true)
+      else
+        next_exists, prev_exists = false
+      end
+      
+      docs.meta_class.instance_eval do        
+        define_method(:next_params) { next_exists ? next_params : false }
+        define_method(:next_query) { next_exists ? "page_params=#{::CGI::escape(next_params.to_json)}" : false }
+        
+        define_method(:prev_params) { prev_exists ? prev_params : false }
+        define_method(:prev_query) { prev_exists ? "page_params=#{::CGI::escape(prev_params.to_json)}" : false }
+      end      
+    end
+    
+    def orig_offset(query, view)
+      if @paginate_params.order_inverted?
+        query.startkey(@orig_paginate_params.endkey).descending(!@orig_paginate_params.descending)
+      else
+        query.startkey(@orig_paginate_params.startkey).descending(@orig_paginate_params.descending)
+      end
+      query.count(1)
+      RelaxDB.retrieve(query.view_path, self, view.view_name, view.map_function).offset
+    end
+    
+  end
+  
+end

data/lib/relaxdb/query.rb

@@ -16,16 +16,17 @@ module RelaxDB
   #
   class Query
     
-    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending skip group)
+    @@params = %w(key startkey startkey_docid endkey endkey_docid count update descending skip group group_level)
     
     @@params.each do |param|
       define_method(param.to_sym) do |val|
-        val ||= ""
-        instance_variable_set("@#{param}".to_sym, val)
+        instance_variable_set("@#{param}", val)
+        # null is meaningful to CouchDB. _set allows us to know that a param has been set, even to nil        
+        instance_variable_set("@#{param}_set", true)
         self
       end
     end
-    
+        
     def initialize(design_doc, view_name)
       @design_doc = design_doc
       @view_name = view_name
@@ -36,12 +37,24 @@ module RelaxDB
       
       query = ""
       @@params.each do |param|
-        val = instance_variable_get("@#{param}")
-        query << "&#{param}=#{::CGI::escape(val.to_json)}" if val
+        val_set = instance_variable_get("@#{param}_set")
+        if val_set
+          val = instance_variable_get("@#{param}")
+          val = val.to_json unless ["startkey_docid", "endkey_docid"].include?(param)
+          query << "&#{param}=#{::CGI::escape(val)}" 
+        end
       end
     
       uri << query.sub(/^&/, "?")
     end
+    
+    def merge(paginate_params)
+      paginate_params.instance_variables.each do |pp|
+        val = paginate_params.instance_variable_get(pp)
+        method_name = pp[1, pp.length]
+        send(method_name, val) if methods.include? method_name
+      end
+    end
         
   end
 

data/lib/relaxdb/relaxdb.rb

@@ -12,6 +12,10 @@ module RelaxDB
       @@db
     end
     
+    def logger
+      @@db.logger
+    end
+    
     # Creates the named database if it doesn't already exist
     def use_db(name)
       db.use_db(name)
@@ -59,7 +63,7 @@ module RelaxDB
       end
       
       data = JSON.parse(resp.body)
-      create_from_hash(data)      
+      ViewResult.new(data)
     end
       
     # Requests the given view from CouchDB and returns a hash.

data/lib/relaxdb/server.rb

@@ -100,7 +100,8 @@ module RelaxDB
     end
     
     def unesc(path)
-       path ? ::CGI::unescape(path) : ""
+      # path
+      path ? ::CGI::unescape(path) : ""
     end
     
     def uri
@@ -111,6 +112,10 @@ module RelaxDB
       @db
     end
     
+    def logger
+      @logger
+    end
+    
     private
     
     def create_db_if_non_existant(name)

data/lib/relaxdb/sorted_by_view.rb

@@ -9,18 +9,9 @@ module RelaxDB
       @atts = atts
     end
 
-    def view_name
-      name = "all_sorted_by"
-
-      @atts.each do |att|
-        name += "_#{att}_and"
-      end
-      name[0, name.size-4]
-    end
-    
     def map_function
       # To guard against non existing attributes in older documents, an OR with an object literal 
-      # is inserted for each emitted key
+      # is inserted for each emitted key. The guard can be emitted in 0.9 trunk.
       # The object literal is the lowest sorting JSON category
         
       # Create the key from the attributes, wrapping it in [] if the key is composite
@@ -36,6 +27,29 @@ module RelaxDB
       }
       QUERY
     end
+    
+    def reduce_function
+      <<-QUERY
+      function(keys, values, rereduce) {
+        return values.length;
+      }
+      QUERY
+    end
+    
+    def view_name
+      name = "all_sorted_by#{suffix}"
+    end
+    
+    def reduce_view_name
+      "reduce_by#{suffix}"
+    end
+    
+    def suffix
+      s = @atts.inject("") do |s, att|
+        s << "_#{att}_and"
+      end
+      s[0, s.size-4]
+    end
   
   end
   

data/spec/design_doc_spec.rb

@@ -16,7 +16,7 @@ describe RelaxDB::DesignDocument do
     
     it "should create a corresponding document in CouchDB" do
       RelaxDB::DesignDocument.get("foo").save      
-      RelaxDB.load("_design/foo").should_not be_nil
+      RelaxDB.load("_design%2Ffoo").should_not be_nil
     end
     
   end
@@ -26,7 +26,7 @@ describe RelaxDB::DesignDocument do
     it "should delete the corresponding document from CouchDB" do
       dd = RelaxDB::DesignDocument.get("foo").save
       dd.destroy!
-      lambda { RelaxDB.load("_design/foo") }.should raise_error
+      lambda { RelaxDB.load("_design%2Ffoo") }.should raise_error
     end
     
   end

data/spec/document_spec.rb

@@ -78,6 +78,32 @@ describe RelaxDB::Document do
         
   end
   
+  describe "user defined property reader" do
+    
+    it "should not effect normal operation" do
+      o = BespokeReader.new(:val => 101).save
+      o = RelaxDB.load o._id
+      o.val.should == 106
+    end
+    
+    it "should not modify internal state" do
+      o = BespokeReader.new(:val => 101).save
+      o = RelaxDB.load o._id
+      o.instance_variable_get(:@val).should == 101
+    end
+            
+  end
+
+  describe "user defined property writer" do
+    
+    it "should not be used" do
+      o = BespokeWriter.new(:val => 101).save
+      o = RelaxDB.load o._id
+      o.val.should == 81
+    end
+        
+  end
+  
   describe "loaded objects" do
     
     it "should contain state as when saved" do
@@ -113,7 +139,6 @@ describe RelaxDB::Document do
     end
     
     it "will result in undefined behaviour when invoked on unsaved objects" do
-      Photo.new.destroy!      
       lambda { Atom.new.destroy! }.should raise_error
     end
   

data/spec/query_spec.rb

@@ -24,21 +24,45 @@ describe RelaxDB::Query do
     end
     
     it "should contain URL and JSON encoded key when the key has been set" do
-      q = RelaxDB::Query.new("Zenith", "mount")
+      q = RelaxDB::Query.new("", "")
       q.key("olympus")
-      q.view_path.should == "_view/Zenith/mount?key=%22olympus%22"
+      q.view_path.should == "_view//?key=%22olympus%22"
     end
     
     it "should honour startkey, endkey and count" do
-      q = RelaxDB::Query.new("Zenith", "all_sorted_by_name_and_height")
+      q = RelaxDB::Query.new("", "")
       q.startkey(["olympus"]).endkey(["vesuvius", 3600]).count(100)
-      q.view_path.should == "_view/Zenith/all_sorted_by_name_and_height?startkey=%5B%22olympus%22%5D&endkey=%5B%22vesuvius%22%2C3600%5D&count=100"
+      q.view_path.should == "_view//?startkey=%5B%22olympus%22%5D&endkey=%5B%22vesuvius%22%2C3600%5D&count=100"
     end
         
-    it "should specify the key as the empty string if key was set to nil" do
+    it "should specify a null key if key was set to nil" do
       q = RelaxDB::Query.new("", "")
       q.key(nil)
-      q.view_path.should == "_view//?key=%22%22"
+      q.view_path.should == "_view//?key=null"
+    end
+
+    it "should specify a null startkey if startkey was set to nil" do
+      q = RelaxDB::Query.new("", "")
+      q.startkey(nil)
+      q.view_path.should == "_view//?startkey=null"
+    end
+
+    it "should specify a null endkey if endkey was set to nil" do
+      q = RelaxDB::Query.new("", "")
+      q.endkey(nil)
+      q.view_path.should == "_view//?endkey=null"
+    end
+    
+    it "should not JSON encode the startkey_docid" do
+      q = RelaxDB::Query.new("", "")
+      q.startkey_docid("foo")
+      q.view_path.should == "_view//?startkey_docid=foo"
+    end
+
+    it "should not JSON encode the endkey_docid" do
+      q = RelaxDB::Query.new("", "")
+      q.endkey_docid("foo")
+      q.view_path.should == "_view//?endkey_docid=foo"
     end
     
   end  

data/spec/spec_models.rb

@@ -12,6 +12,23 @@ class Primitives < RelaxDB::Document
   
 end
 
+class BespokeReader < RelaxDB::Document
+  property :val
+  def val; @val + 5; end
+end
+
+class BespokeWriter < RelaxDB::Document
+  property :val
+  def val=(v); @val = v - 10; end
+end
+
+class Letter < RelaxDB::Document
+  
+  property :letter
+  property :number
+  
+end
+
 class Invite < RelaxDB::Document
   
   property :message

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: paulcarey-relaxdb
 version: !ruby/object:Gem::Version 
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors: 
 - Paul Carey
@@ -60,6 +60,8 @@ files:
 - lib/relaxdb/extlib.rb
 - lib/relaxdb/has_many_proxy.rb
 - lib/relaxdb/has_one_proxy.rb
+- lib/relaxdb/paginate_params.rb
+- lib/relaxdb/paginator.rb
 - lib/relaxdb/query.rb
 - lib/relaxdb/references_many_proxy.rb
 - lib/relaxdb/relaxdb.rb