vote_fu 0.0.11 → 2.0.1

data/lib/vote_fu/concerns/voteable.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module VoteFu
+  module Concerns
+    module Voteable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Configure a model to receive votes
+        #
+        # @example Basic usage
+        #   class Post < ApplicationRecord
+        #     acts_as_voteable
+        #   end
+        #
+        # @example With options
+        #   class Post < ApplicationRecord
+        #     acts_as_voteable counter_cache: true, broadcasts: true
+        #   end
+        #
+        # @param options [Hash] Configuration options
+        # @option options [Boolean] :counter_cache (true) Maintain vote count columns
+        # @option options [Boolean] :broadcasts (true) Broadcast changes via Turbo
+        # @option options [Array<Symbol>] :scopes (nil) Allowed voting scopes
+        def acts_as_voteable(**options)
+          class_attribute :vote_fu_voteable_options, default: {
+            counter_cache: VoteFu.configuration.counter_cache,
+            broadcasts: VoteFu.configuration.turbo_broadcasts,
+            scopes: nil
+          }.merge(options)
+
+          has_many :received_votes,
+                   class_name: "VoteFu::Vote",
+                   as: :voteable,
+                   dependent: :destroy,
+                   inverse_of: :voteable
+
+          include VoteFu::Concerns::Voteable::InstanceMethods
+          extend VoteFu::Concerns::Voteable::ClassMethods
+        end
+
+        # Alternative DSL: declare which models can vote on this one
+        #
+        # @example
+        #   class Post < ApplicationRecord
+        #     voteable_by :users, :admins
+        #   end
+        def voteable_by(*voter_classes, **options)
+          acts_as_voteable(**options)
+
+          class_attribute :vote_fu_allowed_voters, default: voter_classes.map(&:to_s).map(&:classify)
+        end
+      end
+
+      module ClassMethods
+        # Order by total vote value (sum of all vote values)
+        def by_votes(direction = :desc)
+          left_joins(:received_votes)
+            .group(:id)
+            .order(Arel.sql("COALESCE(SUM(vote_fu_votes.value), 0) #{direction.to_s.upcase}"))
+        end
+
+        # Order by vote count
+        def by_vote_count(direction = :desc)
+          left_joins(:received_votes)
+            .group(:id)
+            .order(Arel.sql("COUNT(vote_fu_votes.id) #{direction.to_s.upcase}"))
+        end
+
+        # Items with positive net votes
+        def with_positive_score
+          left_joins(:received_votes)
+            .group(:id)
+            .having("COALESCE(SUM(vote_fu_votes.value), 0) > 0")
+        end
+
+        # Items with any votes
+        def with_votes
+          joins(:received_votes).distinct
+        end
+
+        # Items without any votes
+        def without_votes
+          left_joins(:received_votes)
+            .where(vote_fu_votes: { id: nil })
+        end
+
+        # Trending items (most votes in time period)
+        def trending(since: 24.hours.ago)
+          joins(:received_votes)
+            .where(vote_fu_votes: { created_at: since.. })
+            .group(:id)
+            .order(Arel.sql("COUNT(vote_fu_votes.id) DESC"))
+        end
+      end
+
+      module InstanceMethods
+        # Count of upvotes
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer]
+        def votes_for(scope: nil)
+          received_votes.with_scope(scope).up.count
+        end
+
+        # Count of downvotes
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer]
+        def votes_against(scope: nil)
+          received_votes.with_scope(scope).down.count
+        end
+
+        # Total number of votes
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer]
+        def votes_count(scope: nil)
+          received_votes.with_scope(scope).count
+        end
+
+        # Sum of all vote values
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer]
+        def votes_total(scope: nil)
+          received_votes.with_scope(scope).sum(:value)
+        end
+
+        # Net score (upvotes minus downvotes)
+        # Uses counter cache if available
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer]
+        def plusminus(scope: nil)
+          if has_attribute?(:votes_total) && scope.nil?
+            read_attribute(:votes_total) || 0
+          else
+            votes_for(scope: scope) - votes_against(scope: scope)
+          end
+        end
+
+        # Percentage of upvotes
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Float] 0.0 to 100.0
+        def percent_for(scope: nil)
+          total = votes_count(scope: scope)
+          return 0.0 if total.zero?
+
+          (votes_for(scope: scope).to_f / total * 100).round(1)
+        end
+
+        # Percentage of downvotes
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Float] 0.0 to 100.0
+        def percent_against(scope: nil)
+          total = votes_count(scope: scope)
+          return 0.0 if total.zero?
+
+          (votes_against(scope: scope).to_f / total * 100).round(1)
+        end
+
+        # Check if a voter has voted on this item
+        # @param voter [ActiveRecord::Base] The voter to check
+        # @param direction [Symbol, nil] :up, :down, or nil for any
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Boolean]
+        def voted_by?(voter, direction: nil, scope: nil)
+          vote = received_votes.find_by(voter: voter, scope: scope)
+          return false unless vote
+
+          case direction
+          when nil then true
+          when :up, :positive then vote.up?
+          when :down, :negative then vote.down?
+          else false
+          end
+        end
+
+        # Get all voters who voted on this item
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Array<ActiveRecord::Base>]
+        def voters(scope: nil)
+          received_votes.with_scope(scope).includes(:voter).map(&:voter).uniq
+        end
+
+        # Get voters who upvoted
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Array<ActiveRecord::Base>]
+        def voters_for(scope: nil)
+          received_votes.with_scope(scope).up.includes(:voter).map(&:voter).uniq
+        end
+
+        # Get voters who downvoted
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Array<ActiveRecord::Base>]
+        def voters_against(scope: nil)
+          received_votes.with_scope(scope).down.includes(:voter).map(&:voter).uniq
+        end
+
+        # Wilson Score Lower Bound
+        # @param confidence [Float] Confidence level (0.0 to 1.0)
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Float] Score from 0.0 to 1.0
+        def wilson_score(confidence: 0.95, scope: nil)
+          VoteFu::Algorithms::WilsonScore.call(self, confidence: confidence, scope: scope)
+        end
+
+        # Reddit Hot ranking score
+        # @param gravity [Float] Gravity parameter
+        # @return [Float]
+        def hot_score(gravity: nil)
+          gravity ||= VoteFu.configuration.hot_ranking_gravity
+          VoteFu::Algorithms::RedditHot.call(self, gravity: gravity)
+        end
+
+        # Counter cache methods
+        def increment_vote_counters(value)
+          return unless vote_fu_voteable_options[:counter_cache]
+
+          updates = {}
+          updates[:votes_count] = 1 if has_attribute?(:votes_count)
+          updates[:votes_total] = value if has_attribute?(:votes_total)
+          updates[:upvotes_count] = 1 if has_attribute?(:upvotes_count) && value.positive?
+          updates[:downvotes_count] = 1 if has_attribute?(:downvotes_count) && value.negative?
+
+          self.class.update_counters(id, **updates) if updates.any?
+        end
+
+        def decrement_vote_counters(value)
+          return unless vote_fu_voteable_options[:counter_cache]
+
+          updates = {}
+          updates[:votes_count] = -1 if has_attribute?(:votes_count)
+          updates[:votes_total] = -value if has_attribute?(:votes_total)
+          updates[:upvotes_count] = -1 if has_attribute?(:upvotes_count) && value.positive?
+          updates[:downvotes_count] = -1 if has_attribute?(:downvotes_count) && value.negative?
+
+          self.class.update_counters(id, **updates) if updates.any?
+        end
+
+        def update_vote_counters(old_value, new_value)
+          return unless vote_fu_voteable_options[:counter_cache]
+
+          updates = {}
+
+          if has_attribute?(:votes_total)
+            updates[:votes_total] = new_value - old_value
+          end
+
+          if has_attribute?(:upvotes_count)
+            old_up = old_value.positive? ? 1 : 0
+            new_up = new_value.positive? ? 1 : 0
+            updates[:upvotes_count] = new_up - old_up if new_up != old_up
+          end
+
+          if has_attribute?(:downvotes_count)
+            old_down = old_value.negative? ? 1 : 0
+            new_down = new_value.negative? ? 1 : 0
+            updates[:downvotes_count] = new_down - old_down if new_down != old_down
+          end
+
+          self.class.update_counters(id, **updates) if updates.any?
+        end
+
+        # Broadcast vote updates via Turbo Streams and ActionCable
+        def broadcast_vote_update(vote: nil, action: :updated)
+          return unless vote_fu_voteable_options[:broadcasts]
+
+          # Turbo Streams broadcast
+          if respond_to?(:broadcast_replace_to)
+            broadcast_replace_to(
+              [self, :votes],
+              target: "#{self.class.name.underscore}_#{id}_vote_widget",
+              partial: "vote_fu/votes/widget",
+              locals: { voteable: self }
+            )
+          end
+
+          # ActionCable broadcast (for custom JS handling)
+          if defined?(VoteFu::VotesChannel)
+            VoteFu::VotesChannel.broadcast_vote_update(self, vote: vote, action: action)
+          end
+        end
+
+        # Subscribe to vote updates via ActionCable
+        def vote_stream_name(scope: nil)
+          base = "vote_fu:#{self.class.name}:#{id}"
+          scope.present? ? "#{base}:#{scope}" : base
+        end
+      end
+    end
+  end
+end

data/lib/vote_fu/concerns/voter.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module VoteFu
+  module Concerns
+    module Voter
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Configure a model to cast votes
+        #
+        # @example Basic usage
+        #   class User < ApplicationRecord
+        #     acts_as_voter
+        #   end
+        #
+        # @example With options
+        #   class User < ApplicationRecord
+        #     acts_as_voter allow_self_vote: false
+        #   end
+        #
+        # @param options [Hash] Configuration options
+        # @option options [Boolean] :allow_self_vote (false) Allow voting on self
+        def acts_as_voter(**options)
+          class_attribute :vote_fu_voter_options, default: {
+            allow_self_vote: VoteFu.configuration.allow_self_vote
+          }.merge(options)
+
+          has_many :cast_votes,
+                   class_name: "VoteFu::Vote",
+                   as: :voter,
+                   dependent: :destroy,
+                   inverse_of: :voter
+
+          include VoteFu::Concerns::Voter::InstanceMethods
+          extend VoteFu::Concerns::Voter::ClassMethods
+        end
+
+        # Declare what models this voter votes on (generates helper methods)
+        #
+        # @example
+        #   class User < ApplicationRecord
+        #     acts_as_voter
+        #     votes_on :posts, :comments
+        #   end
+        #
+        #   user.upvote_post(post)
+        #   user.downvote_comment(comment)
+        def votes_on(*model_names, **options)
+          acts_as_voter unless respond_to?(:vote_fu_voter_options)
+
+          model_names.each do |model_name|
+            define_voting_methods_for(model_name, **options)
+          end
+        end
+
+        private
+
+        def define_voting_methods_for(model_name, scopes: nil, **)
+          singular = model_name.to_s.singularize
+
+          # user.upvote_post(post)
+          define_method(:"upvote_#{singular}") do |voteable, scope: nil|
+            vote_on(voteable, value: 1, scope: scope)
+          end
+
+          # user.downvote_post(post)
+          define_method(:"downvote_#{singular}") do |voteable, scope: nil|
+            vote_on(voteable, value: -1, scope: scope)
+          end
+
+          # user.unvote_post(post)
+          define_method(:"unvote_#{singular}") do |voteable, scope: nil|
+            unvote(voteable, scope: scope)
+          end
+
+          # user.toggle_vote_post(post)
+          define_method(:"toggle_vote_#{singular}") do |voteable, scope: nil|
+            toggle_vote(voteable, scope: scope)
+          end
+
+          # user.vote_on_post(post, value: 5)
+          define_method(:"vote_on_#{singular}") do |voteable, value:, scope: nil|
+            vote_on(voteable, value: value, scope: scope)
+          end
+
+          # user.voted_on_post?(post)
+          define_method(:"voted_on_#{singular}?") do |voteable, direction: nil, scope: nil|
+            voted_on?(voteable, direction: direction, scope: scope)
+          end
+
+          # user.vote_value_for_post(post)
+          define_method(:"vote_value_for_#{singular}") do |voteable, scope: nil|
+            vote_value_for(voteable, scope: scope)
+          end
+
+          # Generate scoped methods if scopes provided
+          scopes&.each do |scope_name|
+            define_method(:"vote_on_#{singular}_#{scope_name}") do |voteable, value:|
+              vote_on(voteable, value: value, scope: scope_name)
+            end
+
+            define_method(:"upvote_#{singular}_#{scope_name}") do |voteable|
+              vote_on(voteable, value: 1, scope: scope_name)
+            end
+
+            define_method(:"downvote_#{singular}_#{scope_name}") do |voteable|
+              vote_on(voteable, value: -1, scope: scope_name)
+            end
+          end
+        end
+      end
+
+      module ClassMethods
+        # Find voters who voted on a specific item
+        def voted_on(voteable, direction: nil, scope: nil)
+          votes = VoteFu::Vote.where(voteable: voteable).with_scope(scope)
+          votes = votes.up if direction == :up
+          votes = votes.down if direction == :down
+
+          where(id: votes.where(voter_type: name).select(:voter_id))
+        end
+      end
+
+      module InstanceMethods
+        # Cast a vote on a voteable
+        #
+        # @param voteable [ActiveRecord::Base] The item to vote on
+        # @param value [Integer] Vote value (positive for up, negative for down)
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [VoteFu::Vote] The created or updated vote
+        # @raise [VoteFu::SelfVoteError] If self-voting is disabled
+        # @raise [VoteFu::AlreadyVotedError] If already voted and recast disabled
+        def vote_on(voteable, value:, scope: nil)
+          validate_vote!(voteable, value)
+
+          existing = find_vote_for(voteable, scope: scope)
+
+          if existing
+            handle_existing_vote(existing, value)
+          else
+            cast_votes.create!(voteable: voteable, value: value, scope: scope)
+          end
+        end
+
+        # Upvote a voteable (+1)
+        #
+        # @param voteable [ActiveRecord::Base] The item to vote on
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [VoteFu::Vote]
+        def upvote(voteable, scope: nil)
+          vote_on(voteable, value: 1, scope: scope)
+        end
+
+        # Downvote a voteable (-1)
+        #
+        # @param voteable [ActiveRecord::Base] The item to vote on
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [VoteFu::Vote]
+        def downvote(voteable, scope: nil)
+          vote_on(voteable, value: -1, scope: scope)
+        end
+
+        # Remove a vote
+        #
+        # @param voteable [ActiveRecord::Base] The item to unvote
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [VoteFu::Vote, nil] The destroyed vote or nil
+        def unvote(voteable, scope: nil)
+          find_vote_for(voteable, scope: scope)&.destroy
+        end
+
+        # Toggle vote: remove if exists, upvote if not
+        #
+        # @param voteable [ActiveRecord::Base] The item to toggle
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [VoteFu::Vote, nil]
+        def toggle_vote(voteable, scope: nil)
+          existing = find_vote_for(voteable, scope: scope)
+          if existing
+            existing.destroy
+            nil
+          else
+            upvote(voteable, scope: scope)
+          end
+        end
+
+        # Check if voted on an item
+        #
+        # @param voteable [ActiveRecord::Base] The item to check
+        # @param direction [Symbol, Integer, nil] :up, :down, or specific value
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Boolean]
+        def voted_on?(voteable, direction: nil, scope: nil)
+          vote = find_vote_for(voteable, scope: scope)
+          return false unless vote
+
+          case direction
+          when nil then true
+          when :up, :positive then vote.up?
+          when :down, :negative then vote.down?
+          when Integer then vote.value == direction
+          else false
+          end
+        end
+
+        # Get the vote value for an item
+        #
+        # @param voteable [ActiveRecord::Base] The item
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Integer, nil]
+        def vote_value_for(voteable, scope: nil)
+          find_vote_for(voteable, scope: scope)&.value
+        end
+
+        # Get the vote direction for an item
+        #
+        # @param voteable [ActiveRecord::Base] The item
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [Symbol, nil] :up, :down, :neutral, or nil
+        def vote_direction_for(voteable, scope: nil)
+          find_vote_for(voteable, scope: scope)&.direction
+        end
+
+        # Get all items of a class that this voter voted on
+        #
+        # @param klass [Class] The voteable class
+        # @param scope [Symbol, nil] Optional voting scope
+        # @return [ActiveRecord::Relation]
+        def voted_items(klass, scope: nil)
+          klass.joins(:received_votes)
+               .where(vote_fu_votes: { voter: self, scope: scope })
+               .distinct
+        end
+
+        # Count of votes cast
+        #
+        # @param direction [Symbol, nil] :up, :down, or nil for all
+        # @return [Integer]
+        def vote_count(direction = nil)
+          votes = cast_votes
+          case direction
+          when :up, :positive then votes.up.count
+          when :down, :negative then votes.down.count
+          else votes.count
+          end
+        end
+
+        private
+
+        def find_vote_for(voteable, scope: nil)
+          cast_votes.find_by(voteable: voteable, scope: scope)
+        end
+
+        def validate_vote!(voteable, value)
+          if voteable == self && !vote_fu_voter_options[:allow_self_vote]
+            raise VoteFu::SelfVoteError
+          end
+
+          raise VoteFu::InvalidVoteValueError unless value.is_a?(Integer)
+        end
+
+        def handle_existing_vote(existing, value)
+          if VoteFu.configuration.allow_recast
+            existing.update!(value: value)
+            existing
+          else
+            raise VoteFu::AlreadyVotedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vote_fu/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module VoteFu
+  class Configuration
+    # Can voters change their vote after casting?
+    attr_accessor :allow_recast
+
+    # Can voters cast multiple votes on the same item?
+    attr_accessor :allow_duplicate_votes
+
+    # Can a model vote on itself?
+    attr_accessor :allow_self_vote
+
+    # Automatically maintain counter cache columns?
+    attr_accessor :counter_cache
+
+    # Broadcast vote changes via Turbo Streams?
+    attr_accessor :turbo_broadcasts
+
+    # Use ActionCable for real-time updates?
+    attr_accessor :action_cable
+
+    # Default ranking algorithm (:wilson_score, :reddit_hot, :hacker_news, :simple)
+    attr_accessor :default_ranking
+
+    # Gravity parameter for hot ranking algorithms
+    attr_accessor :hot_ranking_gravity
+
+    def initialize
+      @allow_recast = true
+      @allow_duplicate_votes = false
+      @allow_self_vote = false
+      @counter_cache = true
+      @turbo_broadcasts = true
+      @action_cable = true
+      @default_ranking = :wilson_score
+      @hot_ranking_gravity = 1.8
+    end
+
+    def to_h
+      {
+        allow_recast: allow_recast,
+        allow_duplicate_votes: allow_duplicate_votes,
+        allow_self_vote: allow_self_vote,
+        counter_cache: counter_cache,
+        turbo_broadcasts: turbo_broadcasts,
+        action_cable: action_cable,
+        default_ranking: default_ranking,
+        hot_ranking_gravity: hot_ranking_gravity
+      }
+    end
+  end
+end

data/lib/vote_fu/engine.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Only load engine when Rails is present
+if defined?(Rails::Engine)
+  require "turbo-rails"
+
+  module VoteFu
+    class Engine < ::Rails::Engine
+      isolate_namespace VoteFu
+
+      # Load concerns when ActiveRecord is ready
+      initializer "vote_fu.active_record" do
+        ActiveSupport.on_load(:active_record) do
+          require "vote_fu/concerns/voteable"
+          require "vote_fu/concerns/voter"
+          require "vote_fu/concerns/karmatic"
+
+          include VoteFu::Concerns::Voteable
+          include VoteFu::Concerns::Voter
+          include VoteFu::Concerns::Karmatic
+        end
+      end
+
+      # Include helpers in ActionView
+      initializer "vote_fu.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include VoteFu::VotesHelper
+        end
+      end
+
+      # Set up importmap for Stimulus controllers
+      initializer "vote_fu.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+          app.config.importmap.cache_sweepers << Engine.root.join("app/javascript")
+        end
+      end
+
+      # Append engine assets to asset pipeline
+      initializer "vote_fu.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << Engine.root.join("app/assets/stylesheets")
+        end
+      end
+
+      # Configure generators
+      config.generators do |g|
+        g.test_framework :rspec
+        g.fixture_replacement :factory_bot
+        g.factory_bot dir: "spec/factories"
+      end
+    end
+  end
+end

data/lib/vote_fu/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module VoteFu
+  # Base error class for all VoteFu errors
+  class Error < StandardError; end
+
+  # Raised when a voter attempts to vote again without recast enabled
+  class AlreadyVotedError < Error
+    def initialize(msg = "Already voted on this item")
+      super
+    end
+  end
+
+  # Raised when a model attempts to vote on itself
+  class SelfVoteError < Error
+    def initialize(msg = "Cannot vote on yourself")
+      super
+    end
+  end
+
+  # Raised when an invalid vote value is provided
+  class InvalidVoteValueError < Error
+    def initialize(msg = "Vote value must be an integer")
+      super
+    end
+  end
+
+  # Raised when voteable is not found
+  class VoteableNotFoundError < Error
+    def initialize(msg = "Voteable not found")
+      super
+    end
+  end
+end