paulcarey-relaxdb 0.2.4 → 0.2.5

data/README.textile

@@ -1,16 +1,22 @@
 h3. What's New?
 
+* Denormalisation via derived properties. Examples in spec/derived_properties_spec.rb.
+
+* Validations may be skipped by passing the attribute symbol(s) to @save@ or @save!@.
+
+* Semantic changes for @ has_many#<< @. The parent object is now assigned to the child object *prior* to validation. This potentially breaking change was made to allow child objects to derive properties from a parent object.
+
 * Semantic consistency for load, load!, save and save!. The bang versions raise an exception when their more relaxed siblings would simply return nil.
 
 * Minimal support for CouchDB validation 
 
-* Time storage changes. All Time objects are now converted to UTC and formatted as %Y/%m/%d %H:%M:%S +0000. Storing all Times as UTC should have been happening anyway. Formatting Times as above (as opposed to ISO 8601 as was done prior to 0.2.3) allows the Time strings to be passed directly to Date.new in a JavaScript interpreter. 
+* Time storage changes. All Time objects are now converted to UTC and formatted as @ %Y/%m/%d %H:%M:%S +0000 @. Storing all Times as UTC should have been happening anyway. Formatting Times as above (as opposed to ISO 8601 as was done prior to 0.2.3) allows the Time strings to be passed directly to Date.new in a JavaScript interpreter. 
 
 * Pagination! CouchDB offers great support for retrieving a subset of data, but the housekeeping is tricky. RelaxDB takes care of it.
 ** Note that if you invoke paginate_by on an already created view, the necessary reduce function won't be automatically created. Take a look at SortedByView and create the reduce func by hand.
 * Support for multi key post
 ** For example, @ Numbers.all.sorted_by(:val) { |q| q.keys([1,2,3,5]) } @
-* Works with CouchDB 0.9 trunk as of 2008/10/08. Note that pagination won't work correctly on trunk until issue "COUCHDB-135":http://issues.apache.org/jira/browse/COUCHDB-135 is fixed.
+* Works with CouchDB 0.9 trunk as of 2009/01/02. Note that pagination won't work correctly on trunk until issue "COUCHDB-135":http://issues.apache.org/jira/browse/COUCHDB-135 is fixed.
 
 *Note*: 0.2.1 requires CouchDB 0.9 trunk. 0.2.0 works with CouchDB 0.8 onwards.
 
@@ -154,13 +160,6 @@ RelaxDB::GraphCreator.create
 
 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.2.4"
+GEM_VERSION = "0.2.5"
 AUTHOR = "Paul Carey"
 EMAIL = "paul.p.carey@gmail.com"
 HOMEPAGE = "http://github.com/paulcarey/relaxdb/"

data/lib/relaxdb/document.rb

@@ -31,14 +31,17 @@ module RelaxDB
         end
       end
       
-      create_validator(prop, opts[:validator]) if opts[:validator]
+      if opts[:validator]
+        create_validator(prop, opts[:validator]) 
+      end
       
       if opts[:validation_msg]
-        define_method("#{prop}_validation_msg") do
-          opts[:validation_msg]
-        end
+        create_validation_msg(prop, opts[:validation_msg])
       end
       
+      if opts[:derived]
+        add_derived_prop(prop, opts[:derived])
+      end
     end
 
     def self.properties
@@ -47,14 +50,47 @@ module RelaxDB
     end
     
     def self.create_validator(att, v)
-      define_method("validate_#{att}") do |att_val|
-        if v.is_a? Proc
-          v.call(att_val)
-        elsif respond_to? "validator_#{v}"
-          send("validator_#{v}", att_val)
-        else
-          send(v, att_val)
-        end          
+      method_name = "validate_#{att}"
+      if v.is_a? Proc
+        v.arity == 1 ?
+          define_method(method_name) { |att_val| v.call(att_val) } :
+          define_method(method_name) { |att_val| v.call(att_val, self) }
+      elsif instance_methods.include? "validator_#{v}"
+        define_method(method_name) { |att_val| send("validator_#{v}", att_val, self) }
+      else
+        define_method(method_name) { |att_val| send(v, att_val) }
+      end          
+    end
+    
+    def self.create_validation_msg(prop, validation_msg)
+      if validation_msg.is_a?(Proc)        
+        validation_msg.arity == 1 ?
+          define_method("#{prop}_validation_msg") { |prop_val| validation_msg.call(prop_val) } :
+          define_method("#{prop}_validation_msg") { |prop_val| validation_msg.call(prop_val, self) } 
+      else  
+        define_method("#{prop}_validation_msg") { validation_msg } 
+      end
+    end
+    
+    # See derived_properties_spec.rb for usage
+    def self.add_derived_prop(prop, deriver)
+        source, writer = deriver[0], deriver[1]
+        @derived_prop_writers ||= {}
+        @derived_prop_writers[source] ||= {}
+        @derived_prop_writers[source][prop] = writer
+    end
+    
+    def self.derived_prop_writers
+      @derived_prop_writers ||= {}
+    end
+    
+    def write_derived_props(source)
+      writers = self.class.derived_prop_writers[source]
+      if writers 
+        writers.each do |prop, writer|
+          current_val = send(prop)
+          send("#{prop}=", writer.call(current_val, self))
+        end
       end
     end
 
@@ -67,7 +103,9 @@ module RelaxDB
     property :_id 
     property :_rev    
     
-    def initialize(hash={})
+    def initialize(set_via_writers={}, hash=nil)
+      hash, set_via_writers = set_via_writers, true if set_via_writers.is_a?(Hash)
+      
       # The default _id will be overwritten if loaded from CouchDB
       self._id = UuidGenerator.uuid 
       
@@ -82,28 +120,57 @@ module RelaxDB
         end
       end
       
-      set_attributes(hash)
+      # Maybe use the presence of _rev in hash to determine this rather than 
+      # exposing the implementation detail to clients that choose to override?
+      set_via_writers ? set_attributes(hash) : set_raw_attributes(hash)
     end
     
     def set_attributes(data)
       data.each do |key, val|
         # Only set instance variables on creation - object references are resolved on demand
 
-        # If the variable name ends in _at try to convert it to a Time
-        if key =~ /_at$/
+        # If the variable name ends in _at, _on or _date try to convert it to a Time
+        if [/_at$/, /_on$/, /_date$/].inject(nil) { |i, r| i ||= (key =~ r) }
             val = Time.parse(val).utc rescue val
         end
         
         # Ignore param keys that don't have a corresponding writer
         # This allows us to comfortably accept a hash containing superflous data 
         # such as a params hash in a controller 
+        send("#{key}=".to_sym, val) if methods.include? "#{key}="
+      end
+    end  
+    
+    # Set the raw attribute values rather than setting via the associated writers
+    # The associated writers may invoke validation functions or set derived values
+    # Such behaviour is unwanted when loading from CouchDB and potentially under
+    # other circumstances
+    def set_raw_attributes(data)
+      data.each do |key, val|
+        if [/_at$/, /_on$/, /_date$/].inject(nil) { |i, r| i ||= (key =~ r) }
+            val = Time.parse(val).utc rescue val
+        end
+        
         if methods.include? "#{key}="
-          send("#{key}=".to_sym, val)
+          key = key.to_sym
+          if properties.include? key
+            instance_variable_set("@#{key}".to_sym, val)
+          elsif self.class.has_one_rels.include? key
+            create_or_get_proxy(HasOneProxy, key).target = val
+          else 
+            # belongs_to
+            if key.to_s =~ /_id$/                                            
+              instance_variable_set("@#{key}".to_sym, val)                   
+            else                                                             
+              create_or_get_proxy(BelongsToProxy, key).target = val          
+            end                                                              
+          end                                                                
         end
                 
       end
-    end  
-    
+      
+    end
+        
     def inspect
       s = "#<#{self.class}:#{self.object_id}"
       properties.each do |prop|
@@ -122,9 +189,6 @@ module RelaxDB
       self.class.belongs_to_rels.each do |relationship, opts|
         id = instance_variable_get("@#{relationship}_id".to_sym)
         data["#{relationship}_id"] = id if id
-        if opts[:denormalise]
-          add_denormalised_data(data, relationship, opts)
-        end
       end
       properties.each do |prop|
         prop_val = instance_variable_get("@#{prop}".to_sym)
@@ -133,28 +197,16 @@ module RelaxDB
       data["class"] = self.class.name
       data.to_json      
     end
-    
-    # quick n' dirty denormalisation - explicit denormalisation will probably become a 
-    # permanent fixture of RelaxDB, but quite likely in a different form to this one
-    def add_denormalised_data(data, relationship, opts)
-      obj = send(relationship)
-      if obj
-        opts[:denormalise].each do |prop_name|
-          val = obj.send(prop_name)
-          data["#{relationship}_#{prop_name}"] = val
-        end
-      end
-    end
-    
+        
     # Order changed as of 30/10/2008 to be consistent with ActiveRecord
     # Not yet sure of final implemention for hooks - may lean more towards DM than AR
-    def save
-      return false unless validates?
+    def save(*validation_skip_list)
+      return false unless validates?(*validation_skip_list)
       return false unless before_save
             
       set_created_at if new_document? 
       
-      resp = RelaxDB.db.put("#{_id}", to_json)
+      resp = RelaxDB.db.put(_id, to_json)
       self._rev = JSON.parse(resp.body)["rev"]
 
       after_save
@@ -162,30 +214,33 @@ module RelaxDB
       self
     end  
     
-    def save!
-      save || raise(DocumentNotSaved)
+    def save!(*validation_skip_list)
+      save(*validation_skip_list) || raise(DocumentNotSaved.new(self.errors.to_json))
     end
     
-    def validates?
+    def validates?(*skip_list)
       total_success = true
       properties.each do |prop|
+        next if skip_list.include? prop
         if methods.include? "validate_#{prop}"
           prop_val = instance_variable_get("@#{prop}")
           success = send("validate_#{prop}", prop_val) rescue false
           unless success
             if methods.include? "#{prop}_validation_msg"
-              @errors["#{prop}".to_sym] = send("#{prop}_validation_msg")
+              @errors[prop] = send("#{prop}_validation_msg", prop_val) rescue "validation_msg_exception:invalid:#{prop_val}"
+            else
+              @errors[prop] = "invalid:#{prop}"
             end
           end
           total_success &= success          
         end
       end
       
-      # Unsure whether to pass the id or the doc itself - id is all I need right now 
       self.class.belongs_to_rels.each do |rel, opts|
         if methods.include? "validate_#{rel}"
           rel_val = instance_variable_get("@#{rel}_id")
           success = send("validate_#{rel}", rel_val) rescue false
+          @errors[rel] = "invalid:#{rel_val}" unless success
           total_success &= success
         end
       end
@@ -299,11 +354,13 @@ module RelaxDB
       
       define_method("#{relationship}=") do |new_target|
         create_or_get_proxy(BelongsToProxy, relationship).target = new_target
+        write_derived_props(relationship)
       end
       
       # Allows all writers to be invoked from the hash passed to initialize 
       define_method("#{relationship}_id=") do |id|
         instance_variable_set("@#{relationship}_id".to_sym, id)
+        write_derived_props(relationship)
       end
 
       # Allows belongs_to relationships to be used by the paginator

data/lib/relaxdb/has_many_proxy.rb

@@ -16,13 +16,15 @@ module RelaxDB
     end
 
     def <<(obj)
-      return false unless obj.validates?
       return false if @children.include?(obj)
-      
+
       obj.send("#{@relationship_as_viewed_by_target}=".to_sym, @client)
-      obj.save
-      @children << obj
-      self
+      if obj.save
+        @children << obj
+        self
+      else
+        false
+      end
     end
   
     def clear

data/lib/relaxdb/relaxdb.rb

@@ -151,7 +151,7 @@ module RelaxDB
       klass = data.delete("class")
       if klass
         k = Module.const_get(klass)
-        k.new(data)
+        k.new(false, data)
       else 
         # data is not of a known class
         ViewObject.create(data)

data/lib/relaxdb/server.rb

@@ -63,7 +63,12 @@ module RelaxDB
       
   class CouchDB
         
+    # Used for test instrumentation only i.e. to assert that 
+    # an expected number of GET requests have been issued
+    attr_accessor :get_count    
+        
     def initialize(config)
+      @get_count = 0
       @server = RelaxDB::Server.new(config[:host], config[:port])
       @logger = config[:logger] ? config[:logger] : Logger.new(Tempfile.new('couchdb.log'))
     end
@@ -96,6 +101,7 @@ module RelaxDB
     
     # *ignored allows methods to invoke get or post indifferently
     def get(path=nil, *ignored)
+      @get_count += 1
       @logger.info("GET /#{@db}/#{unesc(path)}")
       @server.get("/#{@db}/#{path}")
     end

data/spec/belongs_to_spec.rb

@@ -75,13 +75,34 @@ describe RelaxDB::BelongsToProxy do
       r.photo.rating.should == r
     end    
     
-    it "should function with the required validator" do
-      c = Class.new(RelaxDB::Document) do
-        belongs_to :foo, :validator => :required
+    describe "validator" do
+      
+      it "should be passed the _id and object" do
+        a = Atom.new(:_id => "atom").save!
+        c = Class.new(RelaxDB::Document) do
+          belongs_to :foo, :validator => lambda { |foo_id, obj| foo_id.reverse == obj._id }
+        end
+        c.new(:_id => "mota", :foo => a).save!
+      end
+      
+      it "may be used with a predefined validator" do
+        c = Class.new(RelaxDB::Document) do
+          belongs_to :foo, :validator => :required
+        end
+        c.new.save.should be_false
       end
-      c.new.save.should be_false
-    end
 
+      it "should be provided with a default error message when validation fails" do
+        c = Class.new(RelaxDB::Document) do
+          belongs_to :foo, :validator => :required
+        end
+        x = c.new
+        x.save
+        x.errors[:foo].should_not be_blank
+      end
+          
+    end
+    
   end
 
 end

data/spec/derived_properties_spec.rb

@@ -0,0 +1,109 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+require File.dirname(__FILE__) + '/spec_models.rb'
+
+# These tests would ideally instrument server.rb, asserting that no
+# HTTP requests are made when retrieving the derived values
+
+class DpInvite < RelaxDB::Document
+  property :event_name, :derived => [:event, lambda { |en, i| i.event.name }]
+  belongs_to :event  
+end
+
+class DpEvent < RelaxDB::Document
+  property :name  
+end
+
+describe RelaxDB::Document, "derived properties" do
+  
+  before(:all) do
+    RelaxDB.configure(:host => "localhost", :port => 5984)  
+  end
+
+  before(:each) do
+    RelaxDB.delete_db "relaxdb_spec_db" rescue "ok"
+    RelaxDB.use_db "relaxdb_spec_db"
+  end
+  
+  it "should have its value updated when the source is updated" do
+    e = DpEvent.new(:name => "shindig")
+    i = DpInvite.new(:event => e)
+    i.event_name.should == "shindig"
+  end
+  
+  it "should have its value persisted" do
+    e = DpEvent.new(:name => "shindig").save!
+    i = DpInvite.new(:event => e).save!
+    
+    RelaxDB.db.get_count = 0
+    i = RelaxDB.load i._id
+    i.event_name.should == "shindig"
+    RelaxDB.db.get_count.should == 1
+  end  
+  
+  it "should have its value updated when the source_id is updated for a saved event" do
+    e = DpEvent.new(:name => "shindig").save!
+    i = DpInvite.new(:event_id => e._id)
+    i.event_name.should == "shindig"
+  end  
+  
+  it "will fail when the source_id is updated for a unsaved event" do
+    # Almost certainly not desired - merely codifying current behaviour
+    e = DpEvent.new(:name => "shindig")
+    lambda { DpInvite.new(:event_id => e._id) }.should raise_error
+  end  
+  
+  it "should only be updated for registered properties" do
+    invite = Class.new(RelaxDB::Document) do
+      property :event_name, :derived => [:foo, lambda { |en, i| i.event.name }]
+      belongs_to :event
+    end
+    
+    event = Class.new(RelaxDB::Document) do
+      property :name
+    end
+    
+    e = event.new(:name => "shindig")
+    i = invite.new(:event => e)
+    i.event_name.should be_nil
+  end
+  
+  it "should have the existing value passed to the first lambda param" do
+    invite = Class.new(RelaxDB::Document) do
+      property :event_name, :derived => [:event, lambda { |en, i| en.nil? ? i.event.name : "bar" }]
+      belongs_to :event
+    end
+    
+    event = Class.new(RelaxDB::Document) do
+      property :name
+    end
+    
+    e1 = event.new(:name => "shindig")
+    e2 = event.new(:name => "shindig2")
+    i = invite.new(:event => e1)
+    i.event = e2
+    i.event_name.should == "bar"
+  end
+  
+  describe "multiple properties" do
+
+    it "should be derivable from the same source" do
+      invite = Class.new(RelaxDB::Document) do
+        property :name, :derived => [:event, lambda { |en, i| i.event.name }]
+        property :location, :derived => [:event, lambda { |en, i| i.event.location }]
+        belongs_to :event
+      end
+
+      event = Class.new(RelaxDB::Document) do
+        property :name
+        property :location
+      end
+
+      e = event.new(:name => "shindig", :location => "city17")
+      i = invite.new(:event => e)
+      i.name.should == "shindig"
+      i.location.should == "city17"
+    end     
+    
+  end
+  
+end

data/spec/document_spec.rb

@@ -131,10 +131,10 @@ describe RelaxDB::Document do
 
   describe "user defined property writer" do
     
-    it "should not be used" do
+    it "may be used with caution" do
       o = BespokeWriter.new(:val => 101).save
       o = RelaxDB.load o._id
-      o.val.should == 81
+      o.val.should == 91
     end
         
   end
@@ -376,13 +376,12 @@ describe RelaxDB::Document do
       r.new(:thumbs_up => 3).save.should be_false
     end
 
-    it "should add the validation error message if supplied, on failure" do
+    it "should pass the property value and object to the validator" do
       r = Class.new(RelaxDB::Document) do
-        property :thumbs_up, :validator => lambda { false }, :validation_msg => "Too many thumbs"
+        property :thumbs_up, :validator => lambda { |tu, o| tu >=0 && o.thumbs_up < 3 }
       end
-      x = r.new
-      x.save
-      x.errors[:thumbs_up].should == "Too many thumbs"
+      r.new(:thumbs_up => 2).save.should be
+      r.new(:thumbs_up => 3).save.should be_false
     end
     
     it "should perform all validations" do
@@ -405,6 +404,15 @@ describe RelaxDB::Document do
       x.save.should == false
     end
     
+    it "should add a default error message if none is specified" do
+      r = Class.new(RelaxDB::Document) do
+        property :foo, :validator => lambda { raise }
+      end
+      x = r.new
+      x.save
+      x.errors[:foo].should_not be_blank
+    end
+    
     it "may be a proc" do
       r = Class.new(RelaxDB::Document) do
         property :thumbs_up, :validator => lambda { false }
@@ -422,6 +430,47 @@ describe RelaxDB::Document do
       r.new(:thumbs_up => 1).save.should be
     end
     
+    it "may be skipped by passing the property symbol to save" do
+      r = Class.new(RelaxDB::Document) do
+        property :thumbs_up, :validator => lambda { raise }
+      end
+      r.new.save!(:thumbs_up)
+    end
+    
+  end
+  
+  describe "validation message" do
+  
+    it "should be set on failure" do
+      r = Class.new(RelaxDB::Document) do
+        property :thumbs_up, :validator => lambda { false }, :validation_msg => "Too many thumbs"
+      end
+      x = r.new
+      x.save
+      x.errors[:thumbs_up].should == "Too many thumbs"
+    end
+    
+    it "may be a proc accepting the prop only" do
+      r = Class.new(RelaxDB::Document) do
+        property :thumbs_up, :validator => lambda { false }, 
+          :validation_msg => lambda { |tu| "#{tu}" }
+      end      
+      x = r.new(:thumbs_up => 13)
+      x.save
+      x.errors[:thumbs_up].should == "13"
+    end
+    
+    
+    it "may be a proc accepting the prop and object" do
+      r = Class.new(RelaxDB::Document) do
+        property :thumbs_up, :validator => lambda { false }, 
+          :validation_msg => lambda { |tu, o| "#{tu} #{o.thumbs_up}" }
+      end      
+      x = r.new(:thumbs_up => 13)
+      x.save
+      x.errors[:thumbs_up].should == "13 13"
+    end
+    
   end
   
   describe "predefined validator" do
@@ -431,7 +480,7 @@ describe RelaxDB::Document do
         property :foo, :validator => :required
         def required; raise; end;
       end
-      c.new(:foo => :bar).save.should be
+      c.new(:foo => :bar).save!.should be
     end
     
     it "should prevent an object from being saved if validation fails" do

data/spec/spec_models.rb

@@ -4,7 +4,7 @@ end
 class Initiative < RelaxDB::Document
   property :x
   attr_reader :foo
-  def initialize(hash={})
+  def initialize(svw=true, hash={})
     super
     @foo = :bar
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: paulcarey-relaxdb
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors: 
 - Paul Carey
@@ -9,7 +9,7 @@ autorequire: relaxdb
 bindir: bin
 cert_chain: []
 
-date: 2008-12-26 00:00:00 -08:00
+date: 2009-01-07 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,8 +77,8 @@ files:
 - lib/relaxdb.rb
 - spec/belongs_to_spec.rb
 - spec/callbacks_spec.rb
-- spec/denormalisation_spec.rb
 - spec/design_doc_spec.rb
+- spec/derived_properties_spec.rb
 - spec/document_spec.rb
 - spec/has_many_spec.rb
 - spec/has_one_spec.rb

data/spec/denormalisation_spec.rb

@@ -1,49 +0,0 @@
-require File.dirname(__FILE__) + '/spec_helper.rb'
-
-# Experimental only for now
-
-class Tree < RelaxDB::Document
-  property :name
-  property :climate
-  has_one :leaf
-end
-
-class Leaf < RelaxDB::Document
-  belongs_to :tree, :denormalise => [:name]
-end
-
-describe RelaxDB::Document, "denormalisation" do
-
-  before(:all) do
-    RelaxDB.configure(:host => "localhost", :port => 5984)  
-  end
-
-  before(:each) do
-    RelaxDB.delete_db "relaxdb_spec_db" rescue "ok"
-    RelaxDB.use_db "relaxdb_spec_db"
-  end
-
-  describe "belongs_to" do
-        
-    it "should store denormalised options in its json representation" do
-      tree = Tree.new(:name => "sapling").save
-      leaf = Leaf.new(:tree => tree)
-      obj = JSON.parse(leaf.to_json)
-      obj["tree_name"].should == "sapling"
-    end
-
-    it "should ignore denormalised options for nil properties" do
-      Leaf.new.to_json
-    end
-    
-    it "should not interfere with normal belongs_to behaviour" do
-      tree = Tree.new(:name => "sapling", :climate => "tropical").save
-      leaf = Leaf.new(:tree => tree).save
-      leaf = RelaxDB.load(leaf._id)
-      leaf.tree.name.should == "sapling"
-      leaf.tree.climate.should == "tropical"
-    end
-    
-  end
-  
-end