voteable_mongo 0.8.1

data/.gitignore

@@ -0,0 +1,12 @@
+*.gem
+Gemfile.lock
+.bundle
+
+.DS_Store
+
+coverage
+rdoc
+pkg
+
+.idea/
+.yardoc/

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm_gemset_create_on_use_flag=1
+rvm use 1.9.2@voteable

data/.watchr

@@ -0,0 +1,23 @@
+# vim:set filetype=ruby:
+def run(cmd)
+  puts cmd
+  system cmd
+end
+
+def spec(file)
+  if File.exists?(file)
+    run("rspec #{file}")
+  else
+    puts("Spec: #{file} does not exist.")
+  end
+end
+
+watch("spec/.*/*_spec\.rb") do |match|
+  puts(match[0])
+  spec(match[0])
+end
+
+watch("lib/(.*/.*)\.rb") do |match|
+  puts(match[1])
+  spec("spec/#{match[1]}_spec.rb")
+end

data/CHANGELOG.rdoc

@@ -0,0 +1,71 @@
+== 0.8.1
+  * Fix gem release bug
+  
+== 0.8.0
+  * Rename to voteable_mongo to support other MongoDB Object-Document Mappers like MongoMapper
+  * Minor fixes and refactoring
+  
+== 0.7.4
+  * Add Votee#up_voters(VoterClass), Votee#down_voters(VoterClass), Votee#voters(VoterClass)
+  * Add Voter scopes: Voter.up_voted_for(votee), Voter.down_voted_for(votee), Voter.voted_for(votee)
+  * Add voteable ..., :index => true options
+  * Optimization on unvote and revote validations
+  * Fix for :up & :down points are nil in rake tasks
+  
+== 0.7.3
+  * Add :return_votee => true option to vote function to warranty always return voteable object
+  * Add Votee.voted?, Votee.up_voted?, Votee.down_voted?
+  * Update parent for ManyToMany relationship
+  * Refactor
+  
+== 0.7.2
+  * Use Collection#find_and_modify to retrieve updated votes data and parent_ids (don't need an extra query to get parent_ids)
+
+== 0.7.1
+  * Add votee#voted_by?(voter or voter_id)
+  * Better doc
+  * Refactor & cleanup source code
+
+== 0.7.0
+  * Use readable field names (up, down, up_count, down_count, count, point) instead of very short field names (u, d, uc, dc, c, p)
+
+== 0.6.4
+  * Drop Voter#votees, Voter#up_votees, Voter#down_votees in favor of Votee#voted_by(voter), Votee#up_voted_by(voter), Votee#down_voted_by(voter) scopes
+
+== 0.6.3
+  * Add rake db:mongoid:voteable:migrate_old_votes to migrate vote data created by version < 0.6.0 to new vote data storage
+
+== 0.6.2
+  * Fix bug: use before_create instead of after_after_initialize
+
+== 0.6.1
+  * Set counters and point to 0 for uninitialized voteable objects in order sort and query
+
+== 0.6.0
+  * Minimize vote data store (using short field names votes.u, votes.d, votes.c ...)
+  * Add Voter#up_votees, Voter#down_votees
+  * Remove index and scope from statistic module. User have to add indexes and scopes manually (see https://github.com/vinova/simple_qa/blob/master/app/models/question.rb)
+  * Bug fixes
+
+== 0.5.0
+  * Rename vote_point to voteable
+
+== 0.4.5
+  * Can use rake db:mongoid:voteable:remake_stats in Rails apps
+  * Use mongoid 2.0.0
+
+== 0.4.4
+  * Add up_votes_count, down_votes_count
+  * Re-generate vote statistic data (counters and point)
+
+== 0.4.3
+  * Wrap vote data in voteable namespace (voteable.up_voters_id, voteable.down_voters_ids, voteable.votes_count ...)
+
+== 0.4.2
+  * Bug fixes
+
+== 0.4.0
+  * Can unvote
+
+== 0.3.5
+  * Use mongoid 2.0.0.rc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in voteable_mongo.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,159 @@
+= Voteable Mongo
+
+voteable_mongo allows you to make your Mongoid::Document (mongo_mapper support coming soon) objects voteable (up or down) and tabulate votes count and votes point for you. For instance, in a forum, a user can vote up (or down) on a post or a comment.
+
+voteable_mongo is built for speed. It uses only one database request per collection to validate data, update data, and get updated data. Initial idea is based on http://cookbook.mongodb.org/patterns/votes
+
+Sample app at https://github.com/vinova/simple_qa
+
+Benchmarks at https://github.com/vinova/voteable_benchmarks
+
+=== Sites using voteable_mongo
+* http://www.amorveneris.com
+* http://zheye.org (https://github.com/huacnlee/quora)
+
+== Installation
+
+=== Rails 3.0.x
+
+To install the gem, add this to your Gemfile
+
+  gem 'mongoid'
+  gem 'voteable_mongo'
+
+After that, remember to run "bundle install"
+
+== Usage
+
+=== Make Post and Comment voteable, User become the voter
+
+post.rb
+
+    class Post
+      include Mongoid::Document
+      include Mongo::Voteable
+
+      # set points for each vote
+      voteable self, :up => +1, :down => -1
+
+      has_many :comments
+    end
+
+comment.rb
+
+    require 'post'
+
+    class Comment
+      include Mongoid::Document
+      include Mongo::Voteable
+
+      belongs_to :post
+
+      voteable self, :up => +1, :down => -3
+
+      # each vote on a comment can affect votes count and point of the related post as well
+      voteable Post, :up => +2, :down => -1
+    end
+
+user.rb
+
+    class User
+      include Mongoid::Document
+      include Mongo::Voter
+    end
+
+=== Make a vote
+
+    @user.vote(@post, :up)
+
+Is equivalent to
+    @user.vote(:votee => @post, :value => :up)
+    @post.vote(:voter => @user, :value => :up)
+
+In case you don't need to init voter and / or votee objects you can
+    @user.vote(:votee_type => 'Post', :votee_id => post_id, :value => :down)
+    @post.vote(:voter_id => user_id, :value => :up)
+    Post.vote(:voter_id => user_id, :votee_id => post_id, :value => :up)
+
+=== Undo a vote
+
+    @user.unvote(@comment)
+
+=== If have voter_id, votee_id and vote value you don't need to init voter and votee objects (suitable for API calls)
+
+New vote
+    Post.vote(:voter_id => user_id, :votee_id => post_id, :value => :up)
+
+Re-vote
+    Post.vote(:voter_id => user_id, :votee_id => post_id, :value => :up, :revote => true)
+
+Un-vote
+    Post.vote(:voter_id => user_id, :votee_id => post_id, :value => :up, :unvote => true)
+    
+In-case you need updated voteable object, add :return_votee => true
+    votee = Post.vote(:voter_id => user_id, :votee_id => post_id, :value => :up, :return_votee => true)
+
+=== Get vote_value
+    
+    @user.vote_value(@post)
+    @user.vote_value(:class_type => 'Post', :votee_id => post_id)
+    @post.vote_value(@user)
+    @post.vote_value(user_id)
+
+=== Check if voted?
+
+    @user.voted?(@post)
+    @user.voted?(:class_type => 'Post', :votee_id => post_id)
+    @post.voted_by?(@user)
+    @post.voted_by?(user_id)
+
+=== Get votes counts and points
+
+    puts @post.votes_point
+    puts @post.votes_count
+    puts @post.up_votes_count
+    puts @post.down_votes_count
+
+=== Get voters given voted object and voter class
+
+    @post.up_voters(User)
+    @post.down_voters(User)
+    @post.voters(User)
+    - or -
+    User.up_voted_for(@post)
+    User.down_voted_for(@post)
+    User.voted_for(@post)
+
+=== Get the list of voted objects of a class
+
+    Post.voted_by(@user)
+    Post.up_voted_by(@user)
+    Post.down_voted_by(@user)
+
+== Utilities
+
+=== Re-generate counters and vote points in case you change :up / :down vote points
+Rails
+    rake mongo:voteable:remake_stats
+Ruby
+    Mongo::Voteable::Tasks.remake_stats
+
+=== Set counters and point to 0 for uninitialized voteable objects in order sort and query
+Rails
+    rake mongo:voteable:init_stats
+Ruby
+    Mongo::Voteable::Tasks::init_stats
+
+=== Migrate from version < 0.7.0
+Rails
+    rake mongo:voteable:migrate_old_votes
+Ruby
+    Mongo::Voteable::Tasks.migrate_old_votes
+
+== Credits
+* Alex Nguyen (alex@vinova.sg) - Author
+* Stefan Nguyen (stefan@vinova.sg) - Unvoting
+
+Copyright (c) 2010-2011 Vinova Pte Ltd (http://vinova.sg)
+
+Licensed under the MIT license.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require "rspec"
+require "rspec/core/rake_task"
+Rspec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => ["spec"]

data/TODO

@@ -0,0 +1,3 @@
+* Add support for mongo_mapper
+* Add options hash validations
+* Refactor specs

data/lib/voteable_mongo.rb

@@ -0,0 +1,10 @@
+require 'mongoid'
+require 'voteable_mongo/voteable'
+require 'voteable_mongo/voter'
+
+require 'voteable_mongo/voteable/tasks'
+
+# Add railtie
+if defined?(Rails)
+  require 'voteable_mongo/railtie'
+end

data/lib/voteable_mongo/railtie.rb

@@ -0,0 +1,17 @@
+module Rails #:nodoc:
+  module VoteableMongo #:nodoc:
+    class Railtie < Rails::Railtie #:nodoc:
+
+      initializer "preload all application models" do |app|
+        config.to_prepare do
+          ::Rails::Mongoid.load_models(app)
+        end
+      end
+
+      rake_tasks do
+        load 'voteable_mongo/railties/database.rake'
+      end
+
+    end
+  end
+end

data/lib/voteable_mongo/railties/database.rake

@@ -0,0 +1,18 @@
+namespace :mongo do
+  namespace :voteable do
+    desc 'Update up_votes_count, down_votes_count, votes_count and votes_point'
+    task :remake_stats => :environment do
+      Mongo::Voteable::Tasks.remake_stats(:log)
+    end
+
+    desc 'Set counters and point to 0 for uninitizized voteable objects'
+    task :init_stats => :environment do
+      Mongo::Voteable::Tasks.init_stats(:log)
+    end
+
+    desc 'Migrate vote data created by version < 0.7.0 to new vote data storage'
+    task :migrate_old_votes => :environment do
+      Mongo::Voteable::Tasks.migrate_old_votes(:log)
+    end
+  end
+end

data/lib/voteable_mongo/version.rb

@@ -0,0 +1,3 @@
+module VoteableMongo
+  VERSION = '0.8.1'
+end

data/lib/voteable_mongo/voteable.rb

@@ -0,0 +1,199 @@
+require 'voteable_mongo/voteable/votes'
+require 'voteable_mongo/voteable/voting'
+
+module Mongo
+  module Voteable
+    extend ActiveSupport::Concern
+
+    included do
+      include ::Mongo::Voteable::Voting
+      
+      field :votes, :type => Votes
+
+      before_create do
+        # Init votes so that counters and point have numeric values (0)
+        self.votes = Votes::DEFAULT_ATTRIBUTES
+      end
+      
+      scope :voted_by, lambda { |voter|
+        voter_id = voter.is_a?(BSON::ObjectId) ? voter : voter.id
+        any_of({ 'votes.up' => voter_id }, { 'votes.down' => voter_id })
+      }
+      
+      scope :up_voted_by, lambda { |voter|
+        voter_id = voter.is_a?(BSON::ObjectId) ? voter : voter.id
+        where( 'votes.up' => voter_id )
+      }
+      
+      scope :down_voted_by, lambda { |voter|
+        voter_id = voter.is_a?(BSON::ObjectId) ? voter : voter.id
+        where( 'votes.down' => voter_id )
+      }
+    end # include
+    
+    # How many points should be assigned for each up or down vote and other options
+    # This hash should manipulated using voteable method
+    VOTEABLE = {}
+
+    module ClassMethods
+      # Set vote point for each up (down) vote on an object of this class
+      # 
+      # @param [Hash] options a hash containings:
+      # 
+      # voteable self, :up => +1, :down => -3
+      # voteable Post, :up => +2, :down => -1, :update_counters => false # skip counter update
+      def voteable(klass = self, options = nil)
+        VOTEABLE[name] ||= {}
+        VOTEABLE[name][klass.name] ||= options
+        if klass == self
+          if options[:index] == true
+            create_voteable_indexes
+          end
+        else
+          VOTEABLE[name][name][:update_parents] ||= true
+        end
+      end
+      
+      # Check if voter_id do a vote on votee_id
+      #
+      # @param [Hash] options a hash containings:
+      #   - :votee_id: the votee document id
+      #   - :voter_id: the voter document id
+      # 
+      # @return [true, false]
+      def voted?(options)
+        validate_and_normalize_vote_options(options)
+        up_voted?(options) || down_voted?(options)
+      end
+      
+      # Check if voter_id do an up vote on votee_id
+      #
+      # @param [Hash] options a hash containings:
+      #   - :votee_id: the votee document id
+      #   - :voter_id: the voter document id
+      # 
+      # @return [true, false]
+      def up_voted?(options)
+        validate_and_normalize_vote_options(options)
+        up_voted_by(options[:voter_id]).where(:_id => options[:votee_id]).count == 1
+      end
+      
+      # Check if voter_id do a down vote on votee_id
+      #
+      # @param [Hash] options a hash containings:
+      #   - :votee_id: the votee document id
+      #   - :voter_id: the voter document id
+      # 
+      # @return [true, false]
+      def down_voted?(options)
+        validate_and_normalize_vote_options(options)
+        down_voted_by(options[:voter_id]).where(:_id => options[:votee_id]).count == 1
+      end
+      
+      private
+      def create_voteable_indexes
+        class_eval do
+          # Compound index _id and voters.up, _id and voters.down
+          # to make up_voted_by, down_voted_by, voted_by scopes and voting faster
+          # Should run in background since it introduce new index value and
+          # while waiting to build, the system can use _id for voting
+          # http://www.mongodb.org/display/DOCS/Indexing+as+a+Background+Operation
+          index [['votes.up', 1], ['_id', 1]], :unique => true
+          index [['votes.down', 1], ['_id', 1]], :unique => true
+
+          # Index counters and point for desc ordering
+          index [['votes.up_count', -1]]
+          index [['votes.down_count', -1]]
+          index [['votes.count', -1]]
+          index [['votes.point', -1]]
+        end
+      end
+    end
+    
+    module InstanceMethods
+      # Make a vote on this votee
+      #
+      # @param [Hash] options a hash containings:
+      #   - :voter_id: the voter document id
+      #   - :value: vote :up or vote :down
+      #   - :revote: change from vote up to vote down
+      #   - :unvote: unvote the vote value (:up or :down)
+      def vote(options)
+        options[:votee_id] = id
+        options[:votee] = self
+        options[:voter_id] ||= options[:voter].id
+
+        if options[:unvote]
+          options[:value] ||= vote_value(options[:voter_id])
+        else
+          options[:revote] ||= vote_value(options[:voter_id]).present?
+        end
+
+        self.class.vote(options)
+      end
+    
+      # Get a voted value on this votee
+      #
+      # @param [Mongoid Object, BSON::ObjectId] voter is Mongoid object or the id of the voter who made the vote
+      def vote_value(voter)
+        voter_id = voter.is_a?(BSON::ObjectId) ? voter : voter.id
+        return :up if up_voter_ids.include?(voter_id)
+        return :down if down_voter_ids.include?(voter_id)
+      end
+    
+      def voted_by?(voter)
+        !!vote_value(voter)
+      end
+
+      # Array of up voter ids
+      def up_voter_ids
+        votes.try(:[], 'up') || []
+      end
+
+      # Array of down voter ids
+      def down_voter_ids
+        votes.try(:[], 'down') || []
+      end
+
+      # Array of voter ids
+      def voter_ids
+        up_voter_ids + down_voter_ids
+      end
+
+      # Get the number of up votes
+      def up_votes_count
+        votes.try(:[], 'up_count') || 0
+      end
+  
+      # Get the number of down votes
+      def down_votes_count
+        votes.try(:[], 'down_count') || 0
+      end
+  
+      # Get the number of votes
+      def votes_count
+        votes.try(:[], 'count') || 0
+      end
+  
+      # Get the votes point
+      def votes_point
+        votes.try(:[], 'point') || 0
+      end
+
+      # Get up voters
+      def up_voters(klass)
+        klass.where(:_id => { '$in' =>  up_voter_ids })
+      end
+
+      # Get down voters
+      def down_voters(klass)
+        klass.where(:_id => { '$in' => down_voter_ids })
+      end
+
+      # Get voters
+      def voters(klass)
+        klass.where(:_id => { '$in' => voter_ids })
+      end
+    end
+  end
+end