custom_counter_cache 0.3.1 → 0.4.0

data/lib/custom_counter_cache/model.rb

@@ -3,81 +3,125 @@ require 'active_support/concern'
 module CustomCounterCache::Model
   extend ActiveSupport::Concern
 
+  included do
+    class_attribute :custom_counter_cache_names, instance_accessor: false, default: []
+    # Per counter name; a new merged hash is assigned so subclasses never mutate their parent's.
+    class_attribute :custom_counter_cache_options, instance_accessor: false, default: {}
+  end
+
   module ClassMethods
-    def define_counter_cache(cache_column, &block)
-      return unless table_exists?
-
-      # counter accessors
-      unless column_names.include?(cache_column.to_s)
-        # Only declare the :counters association once per class -- a model
-        # can have multiple virtual (non-column) counter caches, and
-        # redeclaring has_many :counters for each one just redefines the
-        # same reader/writer methods again, which Ruby warns about under -w.
-        has_many :counters, as: :countable, dependent: :delete_all unless reflect_on_association(:counters)
-        define_method "#{cache_column}" do
-          # check if the counter is loaded
-          if counters.loaded? && counter = counters.detect{|c| c.key == cache_column.to_s }
-            counter.value
+    # Column or counters row is decided on each call, not here, so defining never queries the database.
+    def define_counter_cache(cache_column, touch: nil, store: nil, expires_in: nil, &block)
+      raise ArgumentError, "store: must be :cache or omitted" unless store.nil? || store == :cache
+      name = cache_column.to_s
+      define_counters_association
+      define_cache_cleanup if store == :cache
+      self.custom_counter_cache_names += [name]
+      self.custom_counter_cache_options = custom_counter_cache_options.merge(name => { touch: touch, store: store, expires_in: expires_in })
+
+      custom_counter_cache_methods.module_eval do
+        define_method(name) do
+          case self.class.custom_counter_cache_storage(name)
+          when :column then super()
+          when :cache
+            CustomCounterCache.cache_store.fetch(CustomCounterCache.cache_key(self, name), expires_in: expires_in) { block.call(self) }
           else
-            counters.find_by(key: cache_column.to_s).try(:value).to_i
+            # Once loaded (e.g. includes(:counters)), a missing row means 0, not a query.
+            counter = counters.loaded? ? counters.detect { |c| c.key == name } : counters.find_by(key: name)
+            counter.try(:value).to_i
           end
         end
-        define_method "#{cache_column}=" do |count|
-          if ( counter = counters.find_by(key: cache_column.to_s) )
-            counter.update_attribute :value, count.to_i
+
+        define_method("#{name}=") do |count|
+          case self.class.custom_counter_cache_storage(name)
+          when :column then return super(count)
+          when :cache then return CustomCounterCache.cache_store.write(CustomCounterCache.cache_key(self, name), count, expires_in: expires_in)
+          end
+          count = CustomCounterCache::Model.whole_number!(self, name, count)
+          # Update the loaded Counter itself, or the reader keeps returning its stale value.
+          counter = counters.loaded? ? counters.detect { |c| c.key == name } : counters.find_by(key: name)
+          if counter
+            counter.update_attribute :value, count
           else
-            counters.create key: cache_column.to_s, value: count.to_i
+            begin
+              # Savepoint: on PostgreSQL a failed INSERT would otherwise abort the caller's whole transaction.
+              self.class.transaction(requires_new: true) { counters.create key: name, value: count }
+            rescue ActiveRecord::RecordNotUnique
+              # Lost a create race. A locking read sees the winner's row even under REPEATABLE READ (MySQL).
+              counters.reset
+              counters.lock.find_by!(key: name).update_attribute :value, count
+            end
           end
         end
-      end
 
-      # counter update method
-      define_method "update_#{cache_column}" do
-        if self.class.column_names.include?(cache_column.to_s)
-          update_attribute cache_column, block.call(self)
-        else
-          send "#{cache_column}=", block.call(self)
+        define_method("update_#{name}") do
+          touch_column = self.class.custom_counter_cache_touch_column(name)
+          value = block.call(self)
+          if self.class.custom_counter_cache_storage(name) == :column
+            # One statement, and no callbacks: update_columns, not touch.
+            touch_column ? update_columns(name => value, touch_column => Time.current) : update_column(name, value)
+          else
+            send "#{name}=", value
+            update_column touch_column, Time.current if touch_column
+          end
         end
       end
+    end
 
-    rescue StandardError => e
-      # Support Heroku's database-less assets:precompile pre-deploy step:
-      raise e unless ENV['DATABASE_URL'].to_s.include?('//user:pass@127.0.0.1/')
+    # :cache when declared; otherwise a column if one exists, else a row in the counters table.
+    def custom_counter_cache_storage(name) # :nodoc:
+      return :cache if custom_counter_cache_options.dig(name.to_s, :store) == :cache
+      return :column if column_names.include?(name.to_s)
+      # The counters table's single countable_id can't hold a composite key.
+      if composite_primary_key?
+        raise ArgumentError, "#{self} has a composite primary key, so counter #{name} needs a column or store: :cache"
+      end
+      :counters
     end
 
-    def update_counter_cache(association, cache_column, options = {})
-      return unless table_exists?
+    def custom_counter_cache_touch_column(name) # :nodoc:
+      touch = custom_counter_cache_options.dig(name.to_s, :touch)
+      touch == true ? 'updated_at' : (touch.to_s if touch)
+    end
+
+    # Repairs drift no callback can see (update_all, delete_all, imports). Returns the records processed.
+    def recount_counter_caches(*names, scope: all, batch_size: 1000)
+      names = names.empty? ? custom_counter_cache_names : names.map(&:to_s)
+      unknown = names - custom_counter_cache_names
+      raise ArgumentError, "#{self} has no counter cache named #{unknown.join(', ')}" if unknown.any?
+
+      # Calls update_<name> directly, so CustomCounterCache.skip and .batch don't affect it.
+      # Preload :counters, which the virtual counter writer uses once loaded, to avoid a query per record.
+      scope = scope.includes(:counters) if names.any? { |name| custom_counter_cache_storage(name) == :counters }
+      processed = 0
+      scope.find_each(batch_size: batch_size) do |record|
+        names.each { |name| record.public_send("update_#{name}") }
+        processed += 1
+      end
+      processed
+    end
 
-      association  = association.to_sym
+    # association may be a belongs_to path, e.g. [:article, :user], to recount a grandparent.
+    def update_counter_cache(association, cache_column, options = {})
+      path         = Array(association).map(&:to_sym)
+      association  = path.first
       cache_column = cache_column.to_sym
-      method_name  = "callback_#{association}_#{cache_column}".to_sym
+      method_name  = "callback_#{path.join('_')}_#{cache_column}".to_sym
       reflection   = reflect_on_association(association)
-      foreign_key  = reflection.try(:foreign_key) || reflection.association_foreign_key
+      raise ArgumentError, "#{self} must declare belongs_to :#{association} before update_counter_cache" unless reflection&.belongs_to?
+      foreign_key  = reflection.foreign_key
+      rest         = path.drop(1)
+      path_checked = false
+      timing       = CustomCounterCache.check_timing!(options.fetch(:recount, :after_commit))
 
-      # define callback
       define_method method_name do
-        # update old association
-        if reflection.options[:polymorphic]
-          type_key = "#{association}_type"
-          id_key   = "#{association}_id"
-          if send("saved_change_to_#{id_key}?") || send("saved_change_to_#{type_key}?")
-            old_type = send("saved_change_to_#{type_key}?") ? send("#{type_key}_before_last_save") : send(type_key)
-            old_id   = send("saved_change_to_#{id_key}?")   ? send("#{id_key}_before_last_save")   : send(id_key)
-            if ( old_type && old_id && record = old_type.constantize.find_by(id: old_id) )
-              record.send("update_#{cache_column}")
-            end
-          end
-        else
-          if send("saved_change_to_#{foreign_key}?")
-            old_id = send("#{foreign_key}_before_last_save")
-            if ( old_id && record = reflection.klass.find_by(id: old_id) )
-              record.send("update_#{cache_column}")
-            end
-          end
-        end
-        # update new association
-        if ( record = send(association) )
-          record.send("update_#{cache_column}")
+        # Later steps live on classes that may not be loaded at declaration time, so check them on first use.
+        path_checked ||= CustomCounterCache::Model.check_path!(reflection, rest)
+        owners = [CustomCounterCache::Model.previous_owner(self, reflection), public_send(association)]
+        owners = owners.map { |record| CustomCounterCache::Model.follow_path(record, rest) }
+        # Moving between two records under the same grandparent must recount it once, not twice.
+        owners.compact.uniq { |owner| [owner.class, owner.id] }.each do |owner|
+          CustomCounterCache::Dispatcher.recount(owner, cache_column, timing)
         end
       end
 
@@ -88,13 +132,104 @@ module CustomCounterCache::Model
 
       # set callbacks
       callback_opts = options.slice(:if, :unless, :prepend)
+      update_opts   = callback_opts
+      if options[:on_change]
+        # The keys are always watched so a reassignment recounts the old owner too.
+        watched = Array(options[:on_change]).map(&:to_s) + Array(foreign_key).map(&:to_s)
+        watched << reflection.foreign_type.to_s if reflection.polymorphic?
+        changed = ->(record) { watched.any? { |attribute| record.saved_change_to_attribute?(attribute) } }
+        update_opts = callback_opts.merge(if: Array(options[:if]) + [changed])
+      end
+      # Create isn't gated by :on_change: column defaults aren't saved changes, so new records would be missed.
       after_create  method_name, **callback_opts unless skip_callback.call(:create, options)
-      after_update  method_name, **callback_opts unless skip_callback.call(:update, options)
-      after_destroy method_name, **callback_opts unless skip_callback.call(:destroy, options)
+      after_update  method_name, **update_opts unless skip_callback.call(:update, options)
+      # Not :if/:unless: they test saved changes, which a destroy lacks. An extra recount is never wrong.
+      after_destroy method_name, **options.slice(:prepend) unless skip_callback.call(:destroy, options)
+      # Paranoia's restore skips update callbacks; it defines :restore only once acts_as_paranoid has run.
+      after_restore method_name, **options.slice(:prepend) if respond_to?(:after_restore) && !skip_callback.call(:restore, options)
+    end
+
+    private
+
+    # Included after Active Record's generated attribute methods, so super reaches a real column's accessor.
+    def custom_counter_cache_methods
+      @custom_counter_cache_methods ||= Module.new.tap { |mod| include mod }
+    end
+
+    def define_cache_cleanup
+      return if @custom_counter_cache_cleanup
+      @custom_counter_cache_cleanup = true
+      after_destroy_commit do
+        self.class.custom_counter_cache_names.each do |name|
+          next unless self.class.custom_counter_cache_storage(name) == :cache
+          CustomCounterCache.cache_store.delete(CustomCounterCache.cache_key(self, name))
+        end
+      end
+    end
+
+    def define_counters_association
+      return if reflect_on_association(:counters)
+      has_many :counters, as: :countable, class_name: CustomCounterCache.counter_class_name
+      # Not dependent: :delete_all, which would query the counters table even when every counter is a column.
+      before_destroy do
+        in_table = self.class.custom_counter_cache_names.any? { |name| self.class.custom_counter_cache_storage(name) == :counters }
+        counters.delete_all(:delete_all) if in_table
+      end
+    end
+  end
+
+  # The counters table holds integers. Converting 2.5 to 2 would store a wrong count without a word, so refuse.
+  def self.whole_number!(record, name, value)
+    number =
+      case value
+      when nil then 0
+      when Integer then value
+      when String then Integer(value, 10, exception: false)
+      when Numeric then value.to_i if (!value.respond_to?(:finite?) || value.finite?) && value == value.to_i
+      end
+    return number if number
+    raise ArgumentError, "#{record.class}##{name} is stored in the counters table, which holds whole numbers; got " \
+      "#{value.inspect}. Give it a column of a suitable type, or use store: :cache"
+  end
+
+  # Checks each step up to the first polymorphic one, past which the class varies per record.
+  def self.check_path!(reflection, steps)
+    steps.each do |step|
+      return true if reflection.polymorphic?
+      owner_class = reflection.klass
+      reflection = owner_class.reflect_on_association(step)
+      raise ArgumentError, "#{owner_class} must declare belongs_to :#{step} for update_counter_cache" unless reflection&.belongs_to?
+    end
+    true
+  end
+
+  def self.follow_path(record, steps)
+    steps.reduce(record) do |current, step|
+      break unless current
+      reflection = current.class.reflect_on_association(step)
+      # Only reachable past a polymorphic step: this type has no such parent, so there's nothing to recount.
+      break unless reflection
+      raise ArgumentError, "#{current.class} must declare belongs_to :#{step} for update_counter_cache" unless reflection.belongs_to?
+      current.public_send(step)
+    end
+  end
+
+  # The owner record belonged to before its last save moved it, or nil if it didn't move.
+  # Keys may be composite: only some of their columns may have changed.
+  def self.previous_owner(record, reflection)
+    keys = Array(reflection.foreign_key).map(&:to_s)
+    keys += [reflection.foreign_type] if reflection.polymorphic?
+    return unless keys.any? { |key| record.saved_change_to_attribute?(key) }
+
+    old_values = keys.map { |key| record.saved_change_to_attribute?(key) ? record.attribute_before_last_save(key) : record[key] }
+    return if old_values.any?(&:nil?)
 
-    rescue StandardError => e
-      # Support Heroku's database-less assets:precompile pre-deploy step:
-      raise e unless ENV['DATABASE_URL'].to_s.include?('//user:pass@127.0.0.1/')
+    if reflection.polymorphic?
+      # safe_: the stored type may name a class that has since been renamed or removed.
+      old_klass = old_values.pop.safe_constantize
+      old_klass&.find_by(CustomCounterCache.key_conditions(reflection.association_primary_key(old_klass), old_values))
+    else
+      reflection.klass.find_by(CustomCounterCache.key_conditions(reflection.association_primary_key, old_values))
     end
   end
 end

data/lib/custom_counter_cache/railtie.rb

@@ -0,0 +1,3 @@
+class CustomCounterCache::Railtie < Rails::Railtie
+  rake_tasks { load File.expand_path('../tasks/custom_counter_cache.rake', __dir__) }
+end

data/lib/custom_counter_cache/recount_job.rb

@@ -0,0 +1,16 @@
+begin
+  require 'active_job'
+rescue LoadError
+  raise LoadError, "custom_counter_cache: recount: :later needs Active Job; add 'activejob' to your Gemfile"
+end
+
+module CustomCounterCache
+  # Enqueued by update_counter_cache ..., recount: :later. Takes plain values, not the record, so no GlobalID is needed.
+  class RecountJob < ActiveJob::Base
+    def perform(class_name, id, name)
+      klass = class_name.safe_constantize
+      owner = klass&.find_by(CustomCounterCache.key_conditions(klass.primary_key, id))
+      Dispatcher.locked_recount(owner, name) if owner
+    end
+  end
+end

data/lib/custom_counter_cache/version.rb

@@ -1,5 +1,5 @@
 module CustomCounterCache
 
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 
 end

data/lib/custom_counter_cache.rb

@@ -1,3 +1,37 @@
+require 'active_support'
+require 'active_support/core_ext/module/attribute_accessors'
+
 module CustomCounterCache
-  require 'custom_counter_cache/model'
+  # Model holding counters that have no column. Read when a model defines its first counter, so set it before models load.
+  mattr_accessor :counter_class_name, default: 'Counter'
+  mattr_writer :cache_store, default: nil
+
+  # Where store: :cache counters live: the configured store, else Rails.cache.
+  def self.cache_store
+    store = @@cache_store || (::Rails.cache if defined?(::Rails) && ::Rails.respond_to?(:cache))
+    store or raise ArgumentError, 'store: :cache needs a cache: set CustomCounterCache.cache_store (Rails.cache is used when available)'
+  end
+
+  def self.cache_key(owner, name)
+    "custom_counter_cache/v1/#{owner.class.polymorphic_name}/#{Array(owner.id).join('-')}/#{name}"
+  end
+
+  # Conditions matching columns to values; each may be a single key or a composite one.
+  def self.key_conditions(columns, values) # :nodoc:
+    Array(columns).map(&:to_s).zip(Array(values)).to_h
+  end
+
+  # Callback recounts always run after commit; :later moves them into a job.
+  TIMINGS = %i[after_commit later].freeze
+
+  def self.check_timing!(timing) # :nodoc:
+    raise ArgumentError, "recount: must be one of #{TIMINGS.join(', ')}" unless TIMINGS.include?(timing)
+    # Fail at class load, not on the first save, if Active Job is missing.
+    require 'custom_counter_cache/recount_job' if timing == :later
+    timing
+  end
 end
+
+require 'custom_counter_cache/dispatcher'
+require 'custom_counter_cache/model'
+require 'custom_counter_cache/railtie' if defined?(Rails::Railtie)

data/lib/tasks/custom_counter_cache.rake

@@ -0,0 +1,12 @@
+namespace :custom_counter_cache do
+  desc 'Recount counter caches: MODEL=User [COUNTERS=articles_count,comments_count] [BATCH_SIZE=1000]'
+  task recount: :environment do
+    abort 'MODEL is required, e.g. MODEL=User' if ENV['MODEL'].to_s.empty?
+    model = ENV['MODEL'].safe_constantize
+    abort "#{ENV['MODEL']} is not a model with counter caches" unless model.respond_to?(:recount_counter_caches)
+
+    names = ENV['COUNTERS'].to_s.split(',').map(&:strip).reject(&:empty?)
+    batch_size = Integer(ENV.fetch('BATCH_SIZE', 1000))
+    puts "Recounted #{model.recount_counter_caches(*names, batch_size: batch_size)} #{model} records"
+  end
+end

metadata

@@ -1,22 +1,21 @@
 --- !ruby/object:Gem::Specification
 name: custom_counter_cache
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Cedric Howe
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.2'
+        version: '8.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
@@ -26,10 +25,112 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.2'
+        version: '8.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: discard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: paranoia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -44,22 +145,31 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: ''
+description: Define counter caches computed by an arbitrary block (e.g. a scoped count),
+  refreshed by callbacks on any number of associated models, and stored in a column
+  or a shared polymorphic counters table.
 email: cedric@howe.net
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.rdoc
 - lib/custom_counter_cache.rb
+- lib/custom_counter_cache/dispatcher.rb
 - lib/custom_counter_cache/model.rb
+- lib/custom_counter_cache/railtie.rb
+- lib/custom_counter_cache/recount_job.rb
 - lib/custom_counter_cache/version.rb
-- test/counter_test.rb
-- test/test_helper.rb
-homepage: http://github.com/cedric/custom_counter_cache/
+- lib/tasks/custom_counter_cache.rake
+homepage: https://github.com/cedric/custom_counter_cache
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  source_code_uri: https://github.com/cedric/custom_counter_cache
+  changelog_uri: https://github.com/cedric/custom_counter_cache/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -67,18 +177,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.6
+      version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Custom counter_cache functionality that supports conditions and multiple
   models.
-test_files:
-- test/counter_test.rb
-- test/test_helper.rb
+test_files: []