addywaddy-couch_surfer 0.0.2 → 0.0.4

data/CHANGELOG.md

@@ -1,7 +1,19 @@
+0.0.4 (2009-02-04)
+------------------
+ - `has_many :through`
+ - `has_many :inline`
+ - `create` was in 0.0.2 but forgot to mention it :)
+ - `all` now emits (id, null) so you can use `:keys => [1,2,3,4]` in your query
+ - `format_utc_offset` helper (zdzolton)
+ - Syntax change: 
+   - OLD: `:view => {:name => :by_this_and_that, :query => lambda { {:key => [this_id, id]} }}`
+   - NEW: `:view => :by_this_and_that, :query => lambda { {:key => [this_id, id]} }`
+
 0.0.2 (2009-01-24)
 ------------------
  - `timestamps!` class method now adds instance methods
  - `created_at` and `updated_at` always return an instance of `Time`
+
 0.0.1 (2009-01-21)
 ------------------
- - Initial Release
+ - Initial Release

data/README.md

@@ -1,49 +1,114 @@
-CouchSurfer
-===========
-
+CouchSurfer - CouchDB ORM
+=========================
+---
 Description
 -----------
-CouchSurfer is an extraction of CouchRest::Model from the excellent [CouchRest](http://github.com/jchris/couchrest/ "CouchRest") gem by J. Chris Anderson.
+CouchSurfer is an extraction of CouchRest::Model from the excellent [CouchRest](http://github.com/jchris/couchrest/ "CouchRest") gem by J. Chris Anderson. In addition, it provides association and validation methods.
+
+Associations
+------------
+CouchSurfer provides the following 4 association kinds:
+
+ - `belongs_to`
+ - `has_many`
+ - `has_many :inline`; and
+ - `has_many :through`
+
+All association kinds take an optional `:class_name` option should you want your association to be named differently to the associated model.
+
+    class Page
+      …
+      belongs_to :owner, :class_name => :user
+      …
+    end
+    
+    page = Page.create(…)
+    page.owner # returns an instance of user
+    
+The `belongs_to` associations accept two additional options - `:view` and `query`, enabling you to customise your associations to fit your needs. You must explicitly declare the view on the child model for associations to work
+
+**Example 1: basic**
 
-Features
---------
-- ORM (Extracted from CouchRest::Model)
-- Associations
-  - `has_ many`
-  - `belongs_to`
+    class User
+      …
+      has_many :pages
+      …
+    end
+    
+    class Page
+      …
+      view_by :user_id
+      …
+    end
+    
+    user = User.create(…)
+    10.times {Page.create(…, :user_id => user.id)}
+    user.pages
+    
 
-- Validations
-  - All validations from the [Validatable](http://github.com/jrun/validatable/ "Validatable") gem
-  - `validates_uniqueness_of`
+**Example 2: with options**
 
-Examples
---------
     class Account
-      include CouchSurfer::Model
-      include CouchSurfer::Associations
-  
-      key_accessor :name
-      
-      # Will use the Project.by_account_id view with {:key => account_instance.id}
-      has_many :projects
-      
-      # Uses a custom view and key
-      has_many :employees, :view => {:name => :by_account_id_and_email, 
-          :query => lambda{ {:startkey => [id, nil], :endkey => [id, {}]} }}
+      …
+      has_many :employees,
+          :class_name, :user,
+          :view  => :by_account_id_and_email,
+          :query => lambda { {:startkey => [account_id, nil], :endkey => [account_id, {}]}   }
+      …
+    end
 
+    class User
+      …
+      view_by :account_id, :email # see validation examples below
+      …
     end
 
-    class Project
-      include CouchSurfer::Model
-      include CouchSurfer::Associations
-  
-      key_accessor :name, :account_id
-  
-      belongs_to :account
-  
+    account = Acccount.create(…)
+    10.times {User.create(…, :account_id => acount.id)}
+    account.employees
+    
+**Example 2: :through**
+
+    class Account
+      …
+      has_many :projects,
+          :through => :memberships
+      …
+    end
+
+    class Membership
+      …
       view_by :account_id
+      …
+    end
+    
+    class Project
+      …
+      view_by :account_id, :email # see validation examples below
+      …
     end
 
+    account = Acccount.create(…)
+    10.times do
+      p = Project.create(…)
+      Membership.create(…, :account_id => account.id, :project_id => p.id)
+    end
+    account.projects
+    
+**Note on HasManyThrough**
+
+With reference to the above example, HasManyThrough works by retrieving all memberships associated with the account, collecting their ids and running a [bulk retrieval](http://wiki.apache.org/couchdb/HTTP_view_API "Query Options") on the Project.all view, which is implicitly created for all models and, as of 0.0.4, emits it's id (see CHANGELOG).
+
+*Caveats*
+
+  - Sorting needs to be done client side
+  - The results do not contain any extra information that may be present on the ':through' model.
+
+Validations
+-----------
+Validations, with the exception of `validates_uniqueness_of`, have been implemented using the [Validatable](http://github.com/jrun/validatable/ "Validatable") gem.
+
+**Example**
 
     class Employee
       include CouchSurfer::Model
@@ -62,12 +127,21 @@ Examples
       validates_length_of :postcode, :is => 7, :message => "not the correct length"
       
       # Will use the Employee.by_name view with {:key => employee_instance.name}
-      validates_uniqueness_of :name, :message => "No two Beatles have the same name"
+      validates_uniqueness_of :name
       
-      # Uses a custom view and key
-      validates_uniqueness_of :email, :view => {:name => :by_account_id_and_email,
-        :query => lambda{ {:key => [account_id, email]} }}, :message => "Already taken!"
+      # Uses a custom view and key for uniqueness within a specific scope
+      validates_uniqueness_of :email,
+          :view => :by_account_id_and_email,
+          :query => lambda{ {:key => [account_id, email]} },
+          :message => "The email address for this account is taken"
   
     end
-    
-Please check out the specs as well :)
+
+
+Please check out the specs as well :)
+
+Next
+----
+  - Error handling
+  - association methods with arguments:
+    `@account.projects(:limit => 2, :offset => 1)`

data/Rakefile

@@ -19,7 +19,7 @@ spec = Gem::Specification.new do |s|
   s.version = CouchSurfer::VERSION
   s.date = "2009-01-22"
   s.summary = "ORM based on CouchRest::Model"
-  s.email = "jchris@apache.org"
+  s.email = "adam.groves@gmail.com"
   s.homepage = "http://github.com/addywaddy/couchsurfer"
   s.description = "CouchSurfer provides an ORM for CouchDB, as well as supporting association and validation declarations."
   s.has_rdoc = true

data/lib/couch_surfer/associations.rb

@@ -1,40 +1,56 @@
 require 'rubygems'
 require 'extlib'
-
+module CouchSurfer
+  class InlineCollection < Array
+    def << child
+      child = child.kind_of?( CouchSurfer::Model) ? child.attributes : child
+      super(child)
+    end
+    
+    def delete(child)
+      child = child.kind_of?( CouchSurfer::Model) ? child.attributes : child
+      super(child)
+    end
+  end
+end
 module CouchSurfer
   module Associations
     module ClassMethods
       def has_many *args
-        options = args.last.is_a?(Hash) ? args.pop : {}
+        options = extract_options!(args)
         children = args.first
-        define_method children do |*args|
-          query_params = args.last.is_a?(Hash) ? args.pop : nil
+        if options[:inline]
           name =  ::Extlib::Inflection.camelize(children.to_s.singular)
-          klass = ::Extlib::Inflection.constantize(name)
-          if options[:view].is_a?(Hash)
-            view_name = options[:view][:name]
-            query     = options[:view][:query].is_a?(Proc) ? self.instance_eval(&options[:view][:query]) : nil
+          cast children, :as => [name]
+          before(:save) do
+            if self[children.to_s]
+              self[children.to_s].map!{|child| child.kind_of?( CouchSurfer::Model) ? child.attributes : child}
+            end
           end
-          view_name ||= "by_#{self.class.name.downcase}_id"
-          query ||= {:key => self.id}
-          klass.send(view_name, query)
+          define_method children do |*args|
+            self[children.to_s] ||= CouchSurfer::InlineCollection.new
+          end
+          return
+        end
+        if options[:through]
+          define_method_for_children(options[:through], options)
+          define_method children do
+            name = options[:class_name] || children.to_s.singular
+            class_name =  ::Extlib::Inflection.camelize(name)
+            klass = ::Extlib::Inflection.constantize(class_name)
+            through_items = self.send("#{options[:through]}")
+            query ||= {:keys => through_items.map{|child| child.send("#{name}_id")}}
+            view_name ||= "by_#{self.class.name.downcase}_id"
+            klass.send("all", query)
+          end
+          return
         end
+        define_method_for_children(children, options, options[:class_name])
       end
       
       def belongs_to *args
-        options = args.last.is_a?(Hash) ? args.pop : {}
+        options = extract_options!(args)
         parent = args.first
-        # view_key = "#{parent}_id".to_sym
-        # if options[:identifiers]
-        #   if options[:prepend]
-        #     view_key = options[:identifiers] << view_key
-        #   else 
-        #     view_key = options[:identifiers].unshift(view_key)
-        #   end
-        # end
-        # class_eval do
-        #   view_by *view_key
-        # end
         define_method parent do
           name = ::Extlib::Inflection.camelize(parent.to_s)
           klass = ::Extlib::Inflection.constantize(name)
@@ -48,6 +64,28 @@ module CouchSurfer
           self["#{parent_obj.class.name.downcase}_id"] = parent_obj.id
         end
       end
+      
+      private
+      
+      def extract_options!(args)
+        args.last.is_a?(Hash) ? args.pop : {}
+      end
+      
+      def define_method_for_children(children, options, name = nil)
+        class_name =  ::Extlib::Inflection.camelize(name || children.to_s.singular)
+        define_method children do
+          klass = ::Extlib::Inflection.constantize(class_name)
+          if options[:view]
+            view_name = options[:view]
+          end
+          if options[:query].is_a?(Proc)
+             query = self.instance_eval(&options[:query])
+          end
+          view_name ||= "by_#{self.class.name.downcase}_id"
+          query ||= {:key => self.id}
+          klass.send(view_name, query)
+        end
+      end
     end
     
     def self.included(receiver)

data/lib/couch_surfer/model.rb

@@ -15,6 +15,15 @@ module CouchSurfer
       @database = db
     end
     
+    # Adapted from ActiveSupport Time#formatted_offset
+    def self.format_utc_offset(time)
+      seconds_offset_from_utc = time.utc_offset
+      sign = (seconds_offset_from_utc < 0 ? -1 : 1)
+      hours = seconds_offset_from_utc.abs / 3600
+      minutes = (seconds_offset_from_utc.abs % 3600) / 60
+      "%+03d%02d" % [ hours * sign, minutes ]
+    end
+    
     module ClassMethods
       # override the CouchSurfer::Model-wide default_database
       def use_database db
@@ -154,8 +163,8 @@ module CouchSurfer
         end
         before(:save) do
           time = Time.now
-          usec = time.usec
-          self['updated_at'] = time.strftime("%Y/%m/%d %H:%M:%S.#{time.usec} %z")
+          utc_offset = CouchSurfer::Model.format_utc_offset(time)
+          self['updated_at'] = time.strftime("%Y/%m/%d %H:%M:%S.#{time.usec} #{utc_offset}")
           self['created_at'] = self['updated_at'] if new_document?
         end                  
       end
@@ -290,7 +299,7 @@ module CouchSurfer
       # Deletes any non-current design docs that were created by this class. 
       # Running this when you're deployed version of your application is steadily 
       # and consistently using the latest code, is the way to clear out old design 
-      # docs. Running it to early could mean that live code has to regenerate
+      # docs. Running it too early could mean that live code has to regenerate
       # potentially large indexes.
       def cleanup_design_docs!
         ddocs = all_design_doc_versions
@@ -359,7 +368,7 @@ module CouchSurfer
             'all' => {
               'map' => "function(doc) {
                 if (doc['couchrest-type'] == '#{self.to_s}') {
-                  emit(null,null);
+                  emit(doc['_id'],null);
                 }
               }"
             }
@@ -385,6 +394,7 @@ module CouchSurfer
         end
         self.design_doc_fresh = true
       end
+    
     end
 
     module InstanceMethods

data/lib/couch_surfer/validations.rb

@@ -18,9 +18,9 @@ module CouchSurfer
     
     module InstanceMethods
       def is_unique?(field, options)
-        if options[:view].is_a?(Hash)
-          view_name = options[:view][:name]
-          query     = options[:view][:query].is_a?(Proc) ? self.instance_eval(&options[:view][:query]) : nil
+        if options[:view]
+          view_name = options[:view]
+          query     = options[:query].is_a?(Proc) ? self.instance_eval(&options[:query]) : nil
         end
         view_name ||= "by_#{field}"
         query ||= {:key => self.send(field)}

data/lib/couch_surfer.rb

@@ -2,7 +2,7 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 module CouchSurfer
-  VERSION = '0.0.2'
+  VERSION = '0.0.4'
   autoload :Model,        'couch_surfer/model'
   autoload :Validations,        'couch_surfer/validations'
   autoload :Associations,        'couch_surfer/associations'

data/spec/lib/associations_spec.rb

@@ -3,10 +3,17 @@ require File.dirname(__FILE__) + '/../spec_helper.rb'
 class Account
   include CouchSurfer::Model
   include CouchSurfer::Associations
-  
+
   key_accessor :name
-  
-  has_many :employees, :view => {:name => :by_account_id_and_email, :query => lambda{ {:startkey => [id, nil], :endkey => [id, {}]} }}
+
+  has_many :employees,
+      :view => :by_account_id_and_role,
+      :query => lambda{ {:startkey => [id, nil], :endkey => [id, {}]} }
+
+  has_many :programmers, :class_name => :employee,
+      :view => :by_account_id_and_role,
+      :query => lambda{ {:startkey => [id, "Programmer"], :endkey => [id, "Programmer"]} }
+
   has_many :projects
 
 end
@@ -18,8 +25,22 @@ class Project
   key_accessor :name, :account_id
   
   belongs_to :account
+  has_many :members, :through => :memberships, :class_name => :employee
   
   view_by :account_id
+  view_by :id
+end
+
+class Membership
+  include CouchSurfer::Model
+  include CouchSurfer::Associations
+  
+  key_accessor :project_id, :employee_id
+  belongs_to :project
+  belongs_to :employee
+  
+  view_by :project_id
+  view_by :employee_id
 end
 
 
@@ -27,48 +48,117 @@ class Employee
   include CouchSurfer::Model
   include CouchSurfer::Associations
   
-  key_accessor :email, :account_id
+  key_accessor :email, :account_id, :role
+  
   belongs_to :account
+  has_many :shirts, :inline => true
+  has_many :projects, :through => :memberships
   
-  view_by :account_id, :email
+  view_by :account_id, :role
   
 end
 
+class Shirt
+  include CouchSurfer::Model
+  include CouchSurfer::Associations
+  
+  key_accessor :color
+end
+
 describe CouchSurfer::Associations do
   before(:all) do
     db = CouchRest.database!('couch_surfer-test')
     db.delete!
     CouchSurfer::Model.default_database = CouchRest.database!('http://127.0.0.1:5984/couch_surfer-test')
     @account = Account.create(:name => "My Account")
-    5.times do |i|
-      Employee.create(:email => "foo#{i}@bar.com", :account_id => @account.id)
+    2.times do |i|
+      Employee.create(:email => "foo#{i+1}@bar.com", :account_id => @account.id, :role => "Programmer")
+      Employee.create(:email => "foo#{i+3}@bar.com", :account_id => @account.id, :role => "Engineer")
       Project.create(:name => "Project No. #{i}", :account_id => @account.id)
     end
+    @employee = @account.employees.first
+    @project = @account.projects.first
   end
   
-  describe "An employee" do
-    it "should return it's users" do
-      @other_employee = Employee.create(:email => "woo@war.com", :account_id => "ANOTHER_ACCOUNT_ID")
-      @account.employees.length.should == 5
-      @account.employees.should_not include(@other_employee)
-    end
-    
-    it "should return it's parent account" do
+  describe "belongs_to" do
+    it "should return it's parent" do
       @employee = @account.employees.first
       @employee.account.should == @account
     end
   end
   
-  describe "A project" do
-    it "should return it's projects" do
-      @other_project = Project.create(:name => "Another Project", :account_id => "ANOTHER_ACCOUNT_ID")
-      @account.projects.length.should == 5
-      @account.projects.should_not include(@other_project)
+  describe "has_many" do
+    describe "vanilla" do
+      it "should return it's children" do
+        @account.employees.length.should == 4
+        @account.employees.map{|employee| employee.email}.sort.should == ["foo1@bar.com", "foo2@bar.com", "foo3@bar.com", "foo4@bar.com"]
+      end
+    end
+    
+    describe ":class_name" do
+      it "should return it's children" do
+        @account.programmers.length.should == 2
+      end
+    end
+    describe ":inline" do
+      before(:all) do
+        @employee.shirts.clear
+        @blue_shirt = Shirt.create(:color => "White")
+        @pink_shirt = Shirt.create(:color => "Pink")
+        @employee.shirts << {:color => "Blue"}
+        @employee.shirts << @blue_shirt
+        @employee.save
+        @employee = Employee.get(@employee.id)
+        @employee.shirts << @pink_shirt
+        @employee.save
+      end
+      it "should return it's children" do
+        employee = Employee.get(@employee.id)
+        employee.shirts.each do |shirt|
+          shirt.should be_kind_of(Shirt)
+        end
+        employee.shirts.map{|shirt| shirt.color}.should == %w(Blue White Pink)
+      end
+
+      it "should have a delete method" do
+        employee = Employee.get(@employee.id)
+        employee.shirts.delete(@pink_shirt)
+        employee.save
+        employee = Employee.get(@employee.id)
+        employee.shirts.map{|shirt| shirt.color}.should == %w(Blue White)
+      end
+      
+      it "should have an append method" do
+        employee = Employee.get(@employee.id)
+        employee.shirts << {:color => "Black"}
+        employee.save
+        employee = Employee.get(@employee.id)
+        employee.shirts.map{|shirt| shirt.color}.should == %w(Blue White Black)
+      end
+
     end
     
-    it "should return it's parent account" do
-      @project = @account.projects.first
-      @project.account.should == @account
+    describe ":through" do
+      it "should return it's 'through' children" do
+        @employee.memberships.should be_empty
+      end
+      
+      it "should return it's children" do
+        3.times do |i|
+          p = Project.create(:name => "Project with Invitations No. #{i}", :account_id => @account.id)
+          Membership.create(:employee_id => @employee.id, :project_id => p.id)
+        end
+        
+        7.times do |i|
+          e = Employee.create(:email => "bar#{i}@bar.com", :account_id => @account.id)
+          Membership.create(:employee_id => e.id, :project_id => @project.id)
+        end
+        
+        @employee.memberships.size.should == 3
+        @employee.projects.size.should == 3
+        @project.memberships.size.should == 7
+        @project.members.size.should == 7
+      end
     end
   end
 end

data/spec/lib/model_spec.rb

@@ -72,7 +72,6 @@ class Question
   include CouchSurfer::Model
   
   key_accessor :q, :a
-  couchrest_type = 'Question'
 end
 
 class Person
@@ -351,7 +350,7 @@ describe CouchSurfer::Model do
       @event = Event.get e['id']
     end
     it "should cast created_at to Time" do
-      @event['occurs_at'].should be_an_instance_of(Time)
+      @event.occurs_at.should be_an_instance_of(Time)
     end
   end
   
@@ -534,6 +533,7 @@ describe CouchSurfer::Model do
       foundart.created_at.should == foundart.updated_at
     end
     it "should set the time on update" do
+      sleep 1 # HACK!! Sometimes takes less than a second to call save the second time. Really should mock this!
       @art.save
       @art.created_at.should < @art.updated_at
     end

data/spec/lib/validations_spec.rb

@@ -15,7 +15,7 @@ class User
   validates_format_of   :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
   validates_length_of   :postcode, :is => 7, :message => "not the correct length"
   validates_uniqueness_of :name, :message => "No two Beatles have the same name"
-  validates_uniqueness_of :email, :view => {:name => :by_account_id_and_email, :query => lambda{ {:key => [account_id, email]} }}, :message => "Already taken!"
+  validates_uniqueness_of :email, :view => :by_account_id_and_email, :query => lambda{ {:key => [account_id, email]} }, :message => "Already taken!"
 end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: addywaddy-couch_surfer
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors: 
 - Adam Groves
@@ -40,7 +40,7 @@ dependencies:
         version: 0.12.2
     version: 
 description: CouchSurfer provides an ORM for CouchDB, as well as supporting association and validation declarations.
-email: jchris@apache.org
+email: adam.groves@gmail.com
 executables: []
 
 extensions: []