weathercock 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d2874d2b19beabee7ca9a2d408ce855a1f30560fc44b1f4b9e2efc77b626688
-  data.tar.gz: 1f95984e5dd96a65a07069e0bea20b8f0ad14bcd23770bc8b05b4544a53d12f1
+  metadata.gz: e6f2f450b510bee3dbea48bf0b4e7e37ef24040d82141caaabe45d6dce3c3cb6
+  data.tar.gz: ab78b22090a84493d97b3f5deca74963f150d3ea21af0b47408babb64fdb7985
 SHA512:
-  metadata.gz: cb6fb7895358325549f117b807b75889a0a49ca839deadd4347b4d137c156cd7dac3acf4303b3845a5b11f02bcdc402eb95b8d18feb5fe80b7973676c5cb1939
-  data.tar.gz: 4d347a60ccb2ff6d823bb1586d9ef683702d72a7973ea9a3825f1a3c5f7eeb72f0e110cca5f14f6bf098a5f9076c6d60b6b91ad1b088d6ab85b115294efeda82
+  metadata.gz: e10e7fee6c2e629c994c097920af3226a3f6fdde65a18aed9a85b5556ae6d0a4b4abf78029b833d50d88581745f2517911177ebaee78bbe7de6aef2c78eacb49
+  data.tar.gz: 4a2089ecaceb03a54cb1462504f9b946145b81837db87c4a497650164180c56533246f851ab0c1e1c8f84a337f06faf767c782960e8a9ac6273149f0e69f5766

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## [1.0.0] - 2026-04-15
+## v1.2.0 - 2026-09-16
+
+### Changed
+
+- `union` now reuses an existing destination key instead of always recomputing it, so its 900 second TTL works as a cache
+- `union_dest` now includes `decay_factor` so decayed and non-decayed results no longer share a cache entry
+
+## v1.1.0 - 2026-04-17
+
+### Added
+
+- `#rank` returns the 1-indexed ranking position of an instance; returns `nil` if unranked
+- `#remove_hits` removes all recorded hits for an instance across all keys
+
+### Changed
+
+- Bucket count unified to 90 across all time granularities; data is retained longer
+- `hit_counts` now uses a single ZMSCORE call instead of N ZSCORE calls
+
+## v1.0.0 - 2026-04-15
 
 ### Added
 
@@ -10,6 +29,6 @@
 
 - `require "weathercock"` now loads `Weathercock::Scorable` automatically
 
-## [0.1.0] - 2026-04-15
+## v0.1.0 - 2026-04-15
 
 Initial release.

data/README.md

@@ -53,18 +53,21 @@ myapp:article:views:2026-04         # monthly  (TTL: 3 years)
 
 ```ruby
 # All-time ranking
-Article.top(:views)
+Article.top(:views, limit: 10)
 # => ["42", "7", "133", ...]
 
 # Top article IDs by views over the last 7 days
-Article.top(:views, days: 7)
+Article.top(:views, days: 7, limit: 10)
 
 # Using hours or months
-Article.top(:views, hours: 24)
-Article.top(:views, months: 3)
+Article.top(:views, hours: 24, limit: 10)
+Article.top(:views, months: 3, limit: 10)
 
 # Exponential time decay (recent hits weighted higher)
-Article.top(:views, days: 7, decay_factor: 0.9)
+Article.top(:views, days: 7, decay_factor: 0.9, limit: 10)
+
+# Retrieve all results
+Article.top(:views, limit: nil)
 ```
 
 ### Counting
@@ -85,6 +88,26 @@ Article.hit_counts(:views, ids: [1, 2, 3], days: 7)
 # => {"1" => 42, "2" => 15, "3" => 7}
 ```
 
+### Ranking position
+
+Get the 1-indexed rank of a specific instance:
+
+```ruby
+article.rank(:views)          # all-time
+article.rank(:views, days: 7)
+# => 1
+```
+
+Returns `nil` if the item has no hits.
+
+### Removing hits
+
+Remove all recorded hits for an instance across all keys:
+
+```ruby
+article.remove_hits(:views)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Steepfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  library "date"
+
+  configure_code_diagnostics(D::Ruby.default)
+end

data/lib/weathercock/key_builder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Weathercock
+  class KeyBuilder
+    def initialize(namespace:, klass:)
+      @namespace = namespace
+      @klass_key = klass.name.gsub("::", "_").downcase
+    end
+
+    def base(event)
+      "#{@namespace}:#{@klass_key}:#{event}"
+    end
+
+    def total(base)
+      "#{base}:total"
+    end
+
+    def bucket(base, type, time)
+      case type
+      when :hours  then "#{base}:#{time.strftime("%Y-%m-%d-%H")}"
+      when :days   then "#{base}:#{time.strftime("%Y-%m-%d")}"
+      when :months then "#{base}:#{time.strftime("%Y-%m")}"
+      end
+    end
+
+    def window_keys(base, type, count)
+      now = Time.now
+      case type
+      when :hours
+        count.times.map { |i| bucket(base, type, now - (i * 3600)) }
+      when :days
+        count.times.map { |i| bucket(base, type, now - (i * 86400)) }
+      when :months
+        d = Date.new(now.year, now.month)
+        count.times.map { |i| bucket(base, type, d << i) }
+      end
+    end
+
+    def union_dest(base, type, count, decay_factor: nil)
+      dest = "#{base}:top:#{type}:#{count}"
+      decay_factor ? "#{dest}:decay:#{decay_factor}" : dest
+    end
+  end
+end

data/lib/weathercock/scorable.rb

@@ -1,102 +1,39 @@
 # frozen_string_literal: true
 
-require "date"
-require_relative "../weathercock"
-
 module Weathercock
   module Scorable
-    WEATHERCOCK_BUCKET_TTLS = {
-      hours: 3 * 24 * 3600,
-      days: 3 * 30 * 86400,
-      months: 3 * 12 * 30 * 86400
-    }.freeze
-
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     module ClassMethods
-      def top(event, limit:, decay_factor: nil, **window)
-        stop = limit ? limit - 1 : -1
-        return Weathercock.config.redis.call("ZRANGE", "#{weathercock_base_key(event)}:total", 0, stop, "REV") if window.empty?
-
-        dest = weathercock_union(event, window, decay_factor: decay_factor)
-        Weathercock.config.redis.call("ZRANGE", dest, 0, stop, "REV")
+      def weathercock_scorer
+        @weathercock_scorer ||= Scorer.new(klass: self)
       end
 
-      def hit_counts(event, ids:, **window)
-        redis = Weathercock.config.redis
-        dest = window.empty? ? "#{weathercock_base_key(event)}:total" : weathercock_union(event, window)
-        ids.to_h { |id| [id.to_s, (redis.call("ZSCORE", dest, id.to_s) || "0").to_i] }
-      end
-
-      def weathercock_base_key(event)
-        "#{Weathercock.config.namespace}:#{name.gsub("::", "_").downcase}:#{event}"
-      end
-
-      private
-
-      def weathercock_union(event, window, decay_factor: nil)
-        redis = Weathercock.config.redis
-        base = weathercock_base_key(event)
-        type, count = window.first
-        keys = weathercock_window_keys(base, type, count)
-
-        dest = "#{base}:top:#{type}:#{count}"
-        weights = decay_factor ? count.times.map { |i| (decay_factor**i).round(10) } : nil
-        zunionstore_args = ["ZUNIONSTORE", dest, keys.size, *keys]
-        zunionstore_args += ["WEIGHTS", *weights] if weights
-        redis.call(*zunionstore_args)
-        redis.call("EXPIRE", dest, 900)
-        dest
-      end
-
-      def weathercock_window_keys(base, type, count)
-        now = Time.now
-        case type
-        when :hours
-          count.times.map { |i| weathercock_bucket_key(base, type, now - (i * 3600)) }
-        when :days
-          count.times.map { |i| weathercock_bucket_key(base, type, now - (i * 86400)) }
-        when :months
-          d = Date.new(now.year, now.month)
-          count.times.map { |i| weathercock_bucket_key(base, type, d << i) }
-        end
+      def top(event, limit:, decay_factor: nil, **window)
+        weathercock_scorer.top(event, limit: limit, decay_factor: decay_factor, **window)
       end
 
-      def weathercock_bucket_key(base, type, time)
-        case type
-        when :hours  then "#{base}:#{time.strftime("%Y-%m-%d-%H")}"
-        when :days   then "#{base}:#{time.strftime("%Y-%m-%d")}"
-        when :months then "#{base}:#{time.strftime("%Y-%m")}"
-        end
+      def hit_counts(event, ids:, **window)
+        weathercock_scorer.hit_counts(event, ids: ids, **window)
       end
     end
 
     def hit(event, increment: 1)
-      now = Time.now
-      redis = Weathercock.config.redis
-      base = self.class.weathercock_base_key(event)
-
-      redis.pipelined do |p|
-        p.call("ZINCRBY", "#{base}:total", increment, id.to_s)
-        WEATHERCOCK_BUCKET_TTLS.each do |type, ttl|
-          key = self.class.send(:weathercock_bucket_key, base, type, now)
-          p.call("ZINCRBY", key, increment, id.to_s)
-          p.call("EXPIRE", key, ttl)
-        end
-      end
+      self.class.weathercock_scorer.hit(id, event, increment: increment)
     end
 
     def hit_count(event, **window)
-      if window.empty?
-        score = Weathercock.config.redis.call("ZSCORE", "#{self.class.weathercock_base_key(event)}:total", id.to_s)
-        return score ? score.to_i : 0
-      end
+      self.class.weathercock_scorer.hit_count(id, event, **window)
+    end
+
+    def rank(event, **window)
+      self.class.weathercock_scorer.rank(id, event, **window)
+    end
 
-      dest = self.class.send(:weathercock_union, event, window)
-      score = Weathercock.config.redis.call("ZSCORE", dest, id.to_s)
-      score ? score.to_i : 0
+    def remove_hits(event)
+      self.class.weathercock_scorer.remove_hits(id, event)
     end
   end
 end

data/lib/weathercock/scorer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Weathercock
+  class Scorer
+    BUCKET_COUNT = 90
+
+    BUCKET_TTLS = {
+      hours: BUCKET_COUNT * 3600,
+      days: BUCKET_COUNT * 86400,
+      months: BUCKET_COUNT * 30 * 86400
+    }.freeze
+
+    def initialize(klass:)
+      @redis = Weathercock.config.redis
+      @key_builder = KeyBuilder.new(namespace: Weathercock.config.namespace, klass: klass)
+    end
+
+    def hit(id, event, increment: 1)
+      now = Time.now
+      base = @key_builder.base(event)
+
+      @redis.pipelined do |p|
+        p.call("ZINCRBY", @key_builder.total(base), increment, id.to_s)
+        BUCKET_TTLS.each do |type, ttl|
+          key = @key_builder.bucket(base, type, now)
+          p.call("ZINCRBY", key, increment, id.to_s)
+          p.call("EXPIRE", key, ttl)
+        end
+      end
+    end
+
+    def remove_hits(id, event)
+      base = @key_builder.base(event)
+
+      @redis.pipelined do |p|
+        p.call("ZREM", @key_builder.total(base), id.to_s)
+        BUCKET_TTLS.each_key do |type|
+          @key_builder.window_keys(base, type, BUCKET_COUNT).each do |key|
+            p.call("ZREM", key, id.to_s)
+          end
+        end
+      end
+    end
+
+    def hit_count(id, event, **window)
+      base = @key_builder.base(event)
+      if window.empty?
+        score = @redis.call("ZSCORE", @key_builder.total(base), id.to_s)
+        return score ? score.to_i : 0
+      end
+
+      dest = union(event, window)
+      score = @redis.call("ZSCORE", dest, id.to_s)
+      score ? score.to_i : 0
+    end
+
+    def top(event, limit:, decay_factor: nil, **window)
+      base = @key_builder.base(event)
+      stop = limit ? limit - 1 : -1
+      return @redis.call("ZRANGE", @key_builder.total(base), 0, stop, "REV") if window.empty?
+
+      dest = union(event, window, decay_factor: decay_factor)
+      @redis.call("ZRANGE", dest, 0, stop, "REV")
+    end
+
+    def rank(id, event, **window)
+      base = @key_builder.base(event)
+      dest = window.empty? ? @key_builder.total(base) : union(event, window)
+      r = @redis.call("ZREVRANK", dest, id.to_s)
+      r ? r + 1 : nil
+    end
+
+    def hit_counts(event, ids:, **window)
+      base = @key_builder.base(event)
+      dest = window.empty? ? @key_builder.total(base) : union(event, window)
+      scores = @redis.call("ZMSCORE", dest, *ids.map(&:to_s))
+      ids.zip(scores).to_h do |id, score|
+        [id.to_s, Integer(score || "0")] #: [String, Integer]
+      end
+    end
+
+    private
+
+    def union(event, window, decay_factor: nil)
+      base = @key_builder.base(event)
+      type, count = window.first
+      dest = if decay_factor
+               @key_builder.union_dest(base, type, count, decay_factor: decay_factor)
+             else
+               @key_builder.union_dest(base, type, count)
+             end
+
+      unless @redis.call("EXISTS", dest) == 1
+        keys = @key_builder.window_keys(base, type, count)
+        weights = decay_factor ? count.times.map { |i| (decay_factor**i).round(10) } : nil
+        zunionstore_args = ["ZUNIONSTORE", dest, keys.size, *keys]
+        zunionstore_args += ["WEIGHTS", *weights] if weights
+        @redis.call(*zunionstore_args)
+      end
+      @redis.call("EXPIRE", dest, 900)
+      dest
+    end
+  end
+end

data/lib/weathercock/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Weathercock
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/weathercock.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "weathercock/version"
+require_relative "weathercock/key_builder"
+require_relative "weathercock/scorer"
 require_relative "weathercock/scorable"
 
 module Weathercock

data/sig/weathercock/key_builder.rbs

@@ -0,0 +1,13 @@
+class Weathercock::KeyBuilder
+  def initialize: (namespace: String, klass: Module) -> void
+
+  def base: (Symbol) -> String
+
+  def total: (String) -> String
+
+  def bucket: (String, :hours | :days | :months, Date | Time) -> String
+
+  def window_keys: (String, :hours | :days | :months, Integer) -> Array[String]
+
+  def union_dest: (String, :hours | :days | :months, Integer, ?decay_factor: Float) -> String
+end

data/sig/weathercock/scorable.rbs

@@ -0,0 +1,25 @@
+module Weathercock::Scorable
+  def self.included: (Module) -> void
+  # steep infers self.class in instance methods as singleton(Scorable),
+  # so declare weathercock_scorer here to satisfy the type checker.
+  def self.weathercock_scorer: () -> Weathercock::Scorer
+
+  # Expected to be provided by the including class (e.g. ActiveRecord).
+  def id: () -> Weathercock::id
+
+  def hit: (Symbol, ?increment: Integer) -> void
+
+  def hit_count: (Symbol, ?hours: Integer, ?days: Integer, ?months: Integer) -> Integer
+
+  def rank: (Symbol, ?hours: Integer, ?days: Integer, ?months: Integer) -> Integer?
+
+  def remove_hits: (Symbol) -> void
+end
+
+module Weathercock::Scorable::ClassMethods : Module
+  def weathercock_scorer: () -> Weathercock::Scorer
+
+  def top: (Symbol, limit: Integer?, ?decay_factor: Float, ?hours: Integer, ?days: Integer, ?months: Integer) -> Array[String]
+
+  def hit_counts: (Symbol, ids: Array[Weathercock::id], ?hours: Integer, ?days: Integer, ?months: Integer) -> Hash[String, Integer]
+end

data/sig/weathercock/scorer.rbs

@@ -0,0 +1,20 @@
+class Weathercock::Scorer
+  BUCKET_COUNT: Integer
+  BUCKET_TTLS: Hash[:hours | :days | :months, Integer]
+
+  def initialize: (klass: Module) -> void
+
+  def hit: (Weathercock::id, Symbol, ?increment: Integer) -> void
+
+  def hit_count: (Weathercock::id, Symbol, ?hours: Integer, ?days: Integer, ?months: Integer) -> Integer
+
+  def union: (Symbol, Hash[untyped, untyped], ?decay_factor: Float) -> String
+
+  def top: (Symbol, limit: Integer?, ?decay_factor: Float, ?hours: Integer, ?days: Integer, ?months: Integer) -> Array[String]
+
+  def hit_counts: (Symbol, ids: Array[Weathercock::id], ?hours: Integer, ?days: Integer, ?months: Integer) -> Hash[String, Integer]
+
+  def rank: (Weathercock::id, Symbol, ?hours: Integer, ?days: Integer, ?months: Integer) -> Integer?
+
+  def remove_hits: (Weathercock::id, Symbol) -> void
+end

data/sig/weathercock.rbs

@@ -1,4 +1,18 @@
 module Weathercock
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  type id = Integer | String
+
+  class Error < StandardError
+  end
+
+  class Config
+    attr_accessor namespace: String
+    attr_accessor redis: untyped
+
+    def initialize: () -> void
+  end
+
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: weathercock
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Takafumi ONAKA
@@ -49,11 +49,17 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - compose.yaml
 - lib/weathercock.rb
+- lib/weathercock/key_builder.rb
 - lib/weathercock/scorable.rb
+- lib/weathercock/scorer.rb
 - lib/weathercock/version.rb
 - sig/weathercock.rbs
+- sig/weathercock/key_builder.rbs
+- sig/weathercock/scorable.rbs
+- sig/weathercock/scorer.rbs
 homepage: https://github.com/onk/weathercock
 licenses:
 - MIT
@@ -75,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Hit counter and popularity tracking using Valkey/Redis Sorted Sets
 test_files: []