voting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a4aa7764b2a518434df6182d2f0a0101b9d3079c
+  data.tar.gz: e6a96257d3a5f67a6b8224f21d538285db21c79c
+SHA512:
+  metadata.gz: '01686bdfc40e30e8ce89208e3f3b2e21425382abc2fb7f9dee4f9f2205e5b63886e8564703198d2e6cae610866a839aa8bfa0352cb00ac5d46fe80e1104096ae'
+  data.tar.gz: d3aa1a7f97da1fa5b2c145e7887beb74ab8277007e89b71a70d9baee8a4bc94138c1236c2e4c6e4c58f1e17ea6b5d744794ecf51d6bd8e3f40623a6b106f80e1

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v0.1.0
+
+- First release.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Washington Botelho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,229 @@
+# Voting
+
+[![Build Status](https://travis-ci.org/wbotelhos/voting.svg)](https://travis-ci.org/wbotelhos/voting)
+[![Gem Version](https://badge.fury.io/rb/voting.svg)](https://badge.fury.io/rb/voting)
+[![LiberPay](https://img.shields.io/badge/donate-%3C3-brightgreen.svg)](https://liberapay.com/wbotelhos)
+
+A Binomial proportion confidence interval voting system with scope and cache enabled.
+
+## Description
+
+Voting uses **Binomial proportion confidence interval** to calculate the voting. Inspired on [Evan Miller Article](https://www.evanmiller.org/how-not-to-sort-by-average-rating.html) and used by [Reddit](https://redditblog.com/2009/10/15/reddits-new-comment-sorting-system), [Yelp](https://www.yelpblog.com/2011/02/the-most-romantic-city-on-yelp-is), [Digg](web.archive.org/web/20110415020820/http://about.digg.com/blog/algorithm-experiments-better-comments) and probably other, Voting gives you cache and option to work with scopes over a **binary** voting system.
+
+If you are looking for **5 stars** voting system, check [Rating](https://github.com/wbotelhos/rating) :star2:
+
+## Install
+
+Add the following code on your `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'voting'
+```
+
+Run the following task to create a Voting migration:
+
+```bash
+rails g voting:install
+```
+
+Then execute the migrations to create the tables `voting_votes` and `voting_votings`:
+
+```bash
+rake db:migrate
+```
+
+## Usage
+
+Just add the callback `voting` to your model:
+
+```ruby
+class Author < ApplicationRecord
+  voting
+end
+```
+
+Now this model can vote or receive votes.
+
+### vote
+
+You can vote on some resource:
+
+```ruby
+author_1 = Author.first
+author_2 = Author.last
+resource = Comment.last
+
+author_1.vote(resource, 1)  # +1 vote
+author_2.vote(resource, -1) # -1 vote
+```
+
+### voting
+
+A voted resource exposes a cached data about it state:
+
+```ruby
+resource = Comment.last
+
+resource.voting
+```
+
+It will return a `Voting::Voting` object that keeps:
+
+`author`: the author of this vote;
+
+`estimate`: the Binomial proportion confidence interval value;
+
+`negative`: the sum of negative votes for this resource;
+
+`positive`: the sum of positive votes for this resource;
+
+`resource`: the self object that received this vote;
+
+`scopeable`: the object used as scope;
+
+### vote_for
+
+You can retrieve the vote an author gave to a specific resource:
+
+```ruby
+author   = Author.last
+resource = Comment.last
+
+author.vote_for resource
+```
+
+It will return a `Voting::Vote` object that keeps:
+
+`author`: the author of vote;
+
+`resource`: the resource that received the vote;
+
+`negative`: the -1 value when vote was negative;
+
+`positive`: the 1 value when vote was positive;
+
+`scopeable`: the object used as scope;
+
+### voted?
+
+Maybe you want just to know if some author already voted some resource and receive `true` or `false`:
+
+```ruby
+author   = Author.last
+resource = Comment.last
+
+author.voted? resource
+```
+
+### votes
+
+You can retrieve all votes received by some resource:
+
+```ruby
+resource = Article.last
+
+resource.votes
+```
+
+It will return a collection of `Voting::Vote` object.
+
+### voted
+
+In the same way you can retrieve all votes that some author made:
+
+```ruby
+author = Author.last
+
+author.voted
+```
+
+It will return a collection of `Voting::Vote` object.
+
+### order_by_voting
+
+You can list resource ordered by voting data:
+
+```ruby
+Comment.order_by_voting
+```
+
+It will return a collection of resource ordered by `estimate desc` as default.
+The order column and direction can be changed:
+
+```ruby
+Comment.order_by_voting :negative, :asc
+```
+
+It will return a collection of resource ordered by `Voting::Voting` table data.
+
+### Records
+
+Maybe you want to recover all records, so you can add the suffix `_records` on relations:
+
+```ruby
+author   = Author.last
+resource = Comment.last
+
+author.vote resource, 1
+
+author.voting_records
+
+author.voted_records
+
+comment.voting_records
+```
+
+### As
+
+If you have a model that will only be able to vote but not to receive a vote, configure it as `author`.
+An author model still can be voted, but won't generate a Voting record with all values as zero to warm up the cache.
+
+```ruby
+voting as: :author
+```
+
+### Scoping
+
+If you need to warm up a record with scope, you need to setup the `scoping` relation.
+
+```ruby
+class Resource < ApplicationRecord
+  voting scoping: :categories
+end
+```
+
+Now, when a resource is created, the cache will be generated for each related `category` as `scopeable`.
+
+# Toggle
+
+The toggle functions works out of box, so if you vote up twice or vote twice down, the vote will be canceled.
+When you do that, the vote record is **not destroyed** instead, it receives zero on `negative` and `positive` column.
+
+# Alias
+
+You can to use alias to directly call `vote` with positive or negative data.
+
+```ruby
+author   = Author.last
+resource = Comment.last
+
+author.up   resource # +1
+author.down resource # -1
+```
+
+### Options
+
+`down`: makes a negative vote;
+
+`up`: makes a positive vote;
+
+### References
+
+- [Evan Miller](https://www.evanmiller.org/how-not-to-sort-by-average-rating.html)
+- [Jonathan Landy](http://efavdb.com/ranking-revisited)
+- [Wilson Score Interval](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval)
+- [How to Count Thumb-Ups and Thumb-Downs](http://www.dcs.bbk.ac.uk/~dell/publications/dellzhang_ictir2011.pdf)
+
+## Love it!
+
+Via [PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=X8HEP2878NDEG&item_name=voting) or [LiberPay](https://liberapay.com/wbotelhos). Thanks! (:

data/lib/generators/voting/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Voting
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+
+    desc 'creates Voting migration'
+
+    def create_migration
+      template 'db/migrate/create_voting_tables.rb', "db/migrate/#{timestamp}_create_voting_tables.rb"
+    end
+
+    private
+
+    def timestamp
+      Time.current.strftime '%Y%m%d%H%M%S'
+    end
+  end
+end

data/lib/generators/voting/templates/db/migrate/create_voting_tables.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class CreateVotingTables < ActiveRecord::Migration[5.0]
+  def change
+    create_table :voting_votes do |t|
+      t.integer :negative, default: 0, null: false
+      t.integer :positive, default: 0, null: false
+
+      t.references :author,    index: true, null: false, polymorphic: true
+      t.references :resource,  index: true, null: false, polymorphic: true
+      t.references :scopeable, index: true, null: true,  polymorphic: true
+
+      t.timestamps null: false
+    end
+
+    add_index :voting_votes, %i[author_id author_type resource_id resource_type scopeable_id scopeable_type],
+      name:   :index_voting_votes_on_author_and_resource_and_scopeable,
+      unique: true
+
+    create_table :voting_votings do |t|
+      t.decimal :estimate, default: 0, mull: false, precision: 25, scale: 20
+      t.integer :negative, default: 0, null: false
+      t.integer :positive, default: 0, null: false
+
+      t.references :resource,  index: true, null: false, polymorphic: true
+      t.references :scopeable, index: true, null: true,  polymorphic: true
+
+      t.timestamps null: false
+    end
+
+    add_index :voting_votings, %i[resource_id resource_type scopeable_id scopeable_type],
+      name:   :index_voting_votings_on_resource_and_scopeable,
+      unique: true
+  end
+end

data/lib/voting.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Voting
+end
+
+require 'voting/models/voting/extension'
+require 'voting/models/voting/vote'
+require 'voting/models/voting/voting'
+
+ActiveRecord::Base.include Voting::Extension

data/lib/voting/models/voting/extension.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Voting
+  module Extension
+    extend ActiveSupport::Concern
+
+    included do
+      def down(resource, author: self, scope: nil)
+        vote resource, -1, author: author, scope: scope
+      end
+
+      def up(resource, author: self, scope: nil)
+        vote resource, 1, author: author, scope: scope
+      end
+
+      def vote(resource, value, author: self, scope: nil)
+        Vote.create author: author, resource: resource, scopeable: scope, value: value
+      end
+
+      def vote_for(resource, scope: nil)
+        Vote.vote_for author: self, resource: resource, scopeable: scope
+      end
+
+      def voted?(resource, scope: nil)
+        !vote_for(resource, scope: scope).nil?
+      end
+
+      def votes(scope: nil)
+        votes_records.where scopeable: scope
+      end
+
+      def voted(scope: nil)
+        voted_records.where scopeable: scope
+      end
+
+      def voting(scope: nil)
+        voting_records.find_by scopeable: scope
+      end
+
+      def voting_warm_up(scoping: nil)
+        return Voting.find_or_create_by(resource: self) if scoping.blank?
+
+        [scoping].flatten.compact.map do |attribute|
+          next unless respond_to?(attribute)
+
+          [public_send(attribute)].flatten.compact.map do |object|
+            Voting.find_or_create_by! resource: self, scopeable: object
+          end
+        end.flatten.compact
+      end
+    end
+
+    module ClassMethods
+      def voting(as: nil, scoping: nil)
+        after_save -> { voting_warm_up scoping: scoping }, unless: -> { as == :author }
+
+        has_many :voting_records,
+          as:         :resource,
+          class_name: '::Voting::Voting',
+          dependent:  :destroy
+
+        has_many :votes_records,
+          as:         :resource,
+          class_name: '::Voting::Vote',
+          dependent:  :destroy
+
+        has_many :voted_records,
+          as:         :author,
+          class_name: '::Voting::Vote',
+          dependent:  :destroy
+
+        scope :order_by_voting, ->(column = :estimate, direction = :desc, scope: nil) {
+          scope_values = {
+            scopeable_id:   scope&.id,
+            scopeable_type: scope&.class&.base_class&.name
+          }
+
+          includes(:voting_records)
+            .where(Voting.table_name => scope_values)
+            .order("#{Voting.table_name}.#{column} #{direction}")
+        }
+      end
+    end
+  end
+end

data/lib/voting/models/voting/vote.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Voting
+  class Vote < ActiveRecord::Base
+    self.table_name = 'voting_votes'
+
+    after_save :update_voting
+
+    belongs_to :author,    polymorphic: true
+    belongs_to :resource,  polymorphic: true
+    belongs_to :scopeable, polymorphic: true
+
+    validates :author, :negative, :positive, :resource, presence: true
+    validates :negative, :positive, inclusion: { in: [0, 1] }
+
+    validates :author_id, uniqueness: {
+      case_sensitive: false,
+      scope:          %i[author_type resource_id resource_type scopeable_id scopeable_type]
+    }
+
+    def self.create(author:, resource:, scopeable: nil, value:)
+      record    = find_or_initialize_by(author: author, resource: resource, scopeable: scopeable)
+      attribute = value.positive? ? :positive : :negative
+      canceled  = record.persisted? && value.abs == record[attribute]
+
+      record.negative   = 0
+      record.positive   = 0
+      record[attribute] = value.abs unless canceled
+
+      record.save!
+
+      record
+    end
+
+    def self.vote_for(author:, resource:, scopeable: nil)
+      find_by author: author, resource: resource, scopeable: scopeable
+    end
+
+    private
+
+    def update_voting
+      ::Voting::Voting.update_voting resource, scopeable
+    end
+  end
+end