rs_voteable_mongo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 53b6e38a882ecb70db25219bd78159c08e226bbf
+  data.tar.gz: 10a70421818708ecc107023550022bb31d1db72d
+SHA512:
+  metadata.gz: 167fc70a55bfc367fd4a441a8a7123267b0fc62c5aa58f0a58a20e5824e2847a47f45b1ee01cb5e95c93c2026e187fa1a634c26fe8516f5c09b5694578ad9dad
+  data.tar.gz: 6ca2f3486223cfc1554a2587b42d5884b830f49b50b94917822bf811e1d7ec6bf2edebe082b9198362b6339f8cb70bd57baaa82b42869a20814df60fe530ab6f

data/.gitignore

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

data/.ruby-gemset

@@ -0,0 +1 @@
+votable_mongo

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p247

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,87 @@
+== 0.9.3
+  * Support mongoid ~> 2.0, mongo_mapper ~> 0.9
+  
+== 0.9.2
+  * Replace votee_type to votee_class
+  * Bug fixes
+  
+== 0.9.1
+  * Update gem description
+  
+== 0.9.0
+  * Add MongoMapper support
+  * Simplify voting algorithm
+  * vote / revote / unvote always return voteable object (votee)
+  * Tasks module bug fixes
+  
+== 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 "https://rubygems.org"
+
+# Specify your gem's dependencies in voteable_mongo.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,212 @@
+= Voteable Mongo (for Mongoid 3 / 4)
+
+voteable_mongo allows you to make your Mongoid::Document or MongoMapper::Document objects voteable 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. It's optimized for speed by using only ONE database request per collection to validate, update, and retrieve updated data.
+
+Initial idea based on http://cookbook.mongodb.org/patterns/votes.
+
+Sample app at https://github.com/vinova/simple_qa.
+
+Wonder how fast voteable_mongo is compare to other SQL & MongoDB solutions?
+Visit benchmarks at https://github.com/vinova/voteable_benchmarks
+
+== Why voteable_mongo?
+
+There are various solutions for up / down voting problem (1[https://github.com/medihack/make_voteable], 2[https://github.com/brady8/thumbs_up], 3[https://github.com/icaruswings/mm-voteable], 4[https://github.com/jcoene/mongoid_voteable], ...). Most of them using additional votes table (SQL) or votes collection (MongoDB) to store votes and do data tabulation on that votes table or votes collection.
+
+voteable_mongo is different. It takes advantage of document-oriented database to store all related votes data inside voteable document. That has following benefits:
+
+* Don't have to maintain additional votes table or votes collection.
+
+* When voteable document is loaded, all votes data related to it also be loaded, no more additional database requests to see how many votes this document got, who give up votes who give down vote, total vote points, votes count ...
+
+* When vote up, vote down, revote, unvote, voteable_mongo validates vote data, updates voteable document and retrieves updated data using only ONE database request thanks to atomic findAndModify operation.
+
+* Atomic operations on single document warranty data integrity that makes sure if votes created / changed / deleted their associated counters and points will be updated.
+
+So use voteable_mongo for less maintain cost, data integrity and save database requests for other tasks.
+
+== Sites using voteable_mongo
+* http://www.naiku.net
+* http://www.amorveneris.com
+* http://zheye.org
+
+== Installation
+
+=== Rails 3.x
+
+To install the gem, add this to your Gemfile
+
+  gem 'rs_voteable_mongo'
+
+After that, remember to run "bundle install"
+
+== Usage
+
+=== Make Post and Comment voteable, User become the voter
+
+== Mongoid
+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
+
+
+== MongoMapper
+post.rb
+
+    class Post
+      include MongoMapper::Document
+      include Mongo::Voteable
+
+      # set points for each vote
+      voteable self, :up => +1, :down => -1
+
+      many :comments
+    end
+
+comment.rb
+
+    require 'post'
+
+    class Comment
+      include MongoMapper::Document
+      include Mongo::Voteable
+
+      belongs_to :post
+
+      voteable self, :up => +1, :down => -3
+      voteable Post, :up => +2, :down => -1
+    end
+
+user.rb
+
+    class User
+      include MongoMapper::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_class => 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)
+
+Note: vote function always return updated votee object
+
+=== Get vote_value
+    
+    @user.vote_value(@post)
+    @user.vote_value(:votee_class => Post, :votee_id => post_id)
+    @post.vote_value(@user)
+    @post.vote_value(user_id)
+
+=== Check if voted?
+
+    @user.voted?(@post)
+    @user.voted?(:votee_class => 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
+
+=== 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
+
+=== 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
+
+=== Migrate from voteable_mongoid version < 0.7.0
+Rails
+    rake mongo:voteable:migrate_old_votes
+Ruby
+    Mongo::Voteable::Tasks.migrate_old_votes
+
+== Credits
+* Alex Nguyen - Author
+* Contributors[https://github.com/vinova/voteable_mongo/contributors]
+
+Copyright (c) 2010-2011 Vinova Pte Ltd
+
+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,17 @@
+* Support Mongoid / MongoMapper embedded documents
+
+* Add :foreign_key => ... option to update parents' votes
+  - Reduce time to check relationships and foreign keys
+  - More flexible
+  - Need to change votable interface?
+
+* Support https://github.com/benmyles/mongomatic &
+          https://github.com/carlosparamio/mongo_odm
+  - Don't have scope
+  - Don't have relationships
+
+* Add options hash validations
+
+* Refactor specs
+
+* More test cases for Tasks module

data/lib/rs_votable_mongo.rb

@@ -0,0 +1 @@
+require 'votable_mongo'

data/lib/voteable_mongo/helpers.rb

@@ -0,0 +1,18 @@
+module Mongo
+  module Voteable
+    module Helpers
+
+      def self.try_to_convert_string_to_object_id(x)
+        if defined?(Moped::BSON)
+          x.is_a?(String) && Moped::BSON::ObjectId.legal?(x) ? Moped::BSON::ObjectId.from_string(x) : x
+        else
+          x.is_a?(String) && BSON::ObjectId.legal?(x) ? BSON::ObjectId.from_string(x) : x
+        end
+      end
+
+      def self.get_mongo_id(x)
+        x.respond_to?(:id) ? x.id : x
+      end
+    end
+  end
+end

data/lib/voteable_mongo/integrations/mongoid.rb

@@ -0,0 +1,31 @@
+module Mongo
+  module Voteable
+    module Integrations
+      module Mongoid
+        extend ActiveSupport::Concern
+
+        included do
+          field :votes, :type => Hash, :default => DEFAULT_VOTES
+
+          class << self
+            alias_method :voteable_index, :index
+          end
+        end
+        
+        module ClassMethods
+          def voteable_relation(class_name)
+            relations.find{ |x, r| r.class_name == class_name }.try(:last)
+          end
+
+          def voteable_collection
+            collection
+          end
+
+          def voteable_foreign_key(metadata)
+            metadata.foreign_key.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voteable_mongo/railtie.rb

@@ -0,0 +1,19 @@
+module Rails #:nodoc:
+  module VoteableMongo #:nodoc:
+    class Railtie < Rails::Railtie #:nodoc:
+
+      initializer "preload all application models" do |app|
+        config.to_prepare do
+          if defined?(Mongoid)
+            ::Rails::Mongoid.load_models(app)
+          end
+        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/tasks.rb

@@ -0,0 +1,152 @@
+module Mongo
+  module Voteable
+    module Tasks
+
+      # Set counters and point to 0 for uninitialized voteable objects 
+      # in order sort and query
+      def self.init_stats(log = false)
+        VOTEABLE.each do |class_name, voteable|
+          klass = class_name.constantize
+          klass_voteable = voteable[class_name]
+          puts "Init stats for #{class_name}" if log
+          klass.with(safe: true).where(votes: nil).update_all({ '$set' => {votes: DEFAULT_VOTES} })
+        end
+      end
+      
+      # Re-generate vote counters and vote points
+      def self.remake_stats(log = false)
+        remake_stats_for_all_voteable_classes(log)
+        update_parent_stats(log)
+      end
+
+      # Convert votes from from version < 0.7.0 to new data store
+      def self.migrate_old_votes(log = false)
+        VOTEABLE.each do |class_name, voteable|
+          klass = class_name.constantize
+          klass_voteable = voteable[class_name]
+          puts "* Migrating old vote data for #{class_name} ..." if log
+          migrate_old_votes_for(klass, klass_voteable)
+        end
+      end
+
+      def self.migrate_old_votes_for(klass, voteable)
+        klass.all.each do |doc|
+          # Version 0.6.x use very short field names (u, d, uc, dc, c, p) to minimize 
+          # votes storage but it's not human friendly
+          # Version >= 0.7.0 use readable field names (up, down, up_count, down_count,
+          # count, point)
+          votes = doc['votes'] || doc['voteable'] || {}
+
+          up_voter_ids = votes['up'] || votes['u'] ||
+            votes['up_voter_ids'] || doc['up_voter_ids'] || []
+
+          down_voter_ids = votes['down'] || votes['d'] ||
+            votes['down_voter_ids'] || doc['down_voter_ids'] || []
+
+          up_count = up_voter_ids.size
+          down_count = down_voter_ids.size
+
+          klass.with(safe: true).where(_id: doc.id).update_all(
+            '$set' => {
+              'votes' => {
+                'up' => up_voter_ids,
+                'down' => down_voter_ids,
+                'up_count' => up_count,
+                'down_count' => down_count,
+                'count' => up_count + down_count,
+                'point' => voteable[:up].to_i*up_count + voteable[:down].to_i*down_count
+              }
+            },
+            '$unset' => {
+              'up_voter_ids' => true,
+              'down_voter_ids' => true,
+              'votes_count' => true,
+              'votes_point' => true,
+              'voteable' => true
+            }
+          )
+        end
+      end
+      
+        
+      def self.remake_stats_for_all_voteable_classes(log)
+        VOTEABLE.each do |class_name, voteable|
+          klass = class_name.constantize
+          klass_voteable = voteable[class_name]
+          puts "Generating stats for #{class_name}" if log
+          klass.all.each{ |doc|
+            remake_stats_for(doc, klass_voteable)
+          }
+        end
+      end
+
+  
+      def self.remake_stats_for(doc, voteable)
+        up_count = doc.up_voter_ids.length
+        down_count = doc.down_voter_ids.length
+        doc.update_attributes(
+          'votes' => {
+            'up' => doc.up_voter_ids,
+            'down' => doc.down_voter_ids,
+            'up_count' => up_count,
+            'down_count' => down_count,
+            'count' => up_count + down_count,
+            'point' => voteable[:up].to_i*up_count + voteable[:down].to_i*down_count
+          }
+        )
+      end
+
+
+      def self.update_parent_stats(log)
+        VOTEABLE.each do |class_name, voteable|
+          klass = class_name.constantize
+          voteable.each do |parent_class_name, parent_voteable|
+            metadata = klass.voteable_relation(parent_class_name)
+            if metadata
+              parent_class = parent_class_name.constantize
+              foreign_key = klass.voteable_foreign_key(metadata)
+              puts "Updating stats for #{class_name} > #{parent_class_name}" if log
+              klass.all.each{ |doc|
+                update_parent_stats_for(doc, parent_class, foreign_key, parent_voteable)
+              }
+            end
+          end
+        end
+      end
+  
+  
+      def self.update_parent_stats_for(doc, parent_class, foreign_key, voteable)
+        parent_id = doc.read_attribute(foreign_key.to_sym)
+        if parent_id
+          up_count = doc.up_voter_ids.length
+          down_count = doc.down_voter_ids.length
+      
+          return if up_count == 0 && down_count == 0
+
+          inc_options = {
+            'votes.point' => voteable[:up].to_i*up_count + voteable[:down].to_i*down_count
+          }
+        
+          unless voteable[:update_counters] == false
+            inc_options.merge!(
+              'votes.count' => up_count + down_count,
+              'votes.up_count' => up_count,
+              'votes.down_count' => down_count
+            )
+          end
+
+          parent_ids = parent_id.is_a?(Array) ? parent_id : [ parent_id ]
+          
+          parent_class.with(safe: true).where(:_id.in => parent_ids).update_all({ '$inc' =>  inc_options })
+        end
+      end
+
+      private_class_method  :migrate_old_votes_for, 
+                            :remake_stats_for,
+                            :remake_stats_for_all_voteable_classes,
+                            :update_parent_stats,
+                            :update_parent_stats_for                            
+      
+    end
+  end
+end

data/lib/voteable_mongo/version.rb

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