weathercock 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69167dba72d21575ef52f1c799423a78ff435b8fa42a8ea60eac368a1dbe680b
-  data.tar.gz: 586f93c2471f63dc178de81ee96c3d39dd205c41ba69984535d2d14012b04f2c
+  metadata.gz: cc7554f2d86d4cd3499ea0aa89d77bc327e9667b16257b234f00391d82118f8b
+  data.tar.gz: 7687c05fe5724b8ec134bfbaf9fc4689b799415f368627a85de790b8ddcd7073
 SHA512:
-  metadata.gz: 362d33770a45bbf057ee4907dd978ce032444e134972f841dc903c52f7df2511aa2c5556abfe1d31008b6e10b0841c0b98ab8ae0aabc34564af1cbd7fbce642c
-  data.tar.gz: d4d6f1434f014a87a0906732960217ba1ebbbe9d8ab3660e70544da151a856696f08fa2b07f938ced057440a6ab5d1677eec21ae4820a3ecac735bb2a5950d2f
+  metadata.gz: 9bb7bf12377be72a41e51a5de234475e2cbab1d3a8333b47865da959053d482b5bcb762d4c13fa00ed142a95bf64c531e2b04a22a608969440a7feb45dd881dc
+  data.tar.gz: 90e5eafb164fe1fdc2b11167b28a9f9a6fda24dc1be2ed98e987505b05bb4aabe7f8bb7b66b9141e658bdba0e70cc36a808be3a557a42ff19c944ef115d020ff

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 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
+
+- `.top` now accepts a required `limit` keyword argument; pass `nil` to retrieve all results
+
+### Fixed
+
+- `require "weathercock"` now loads `Weathercock::Scorable` automatically
+
+## 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/lib/weathercock/key_builder.rb

@@ -0,0 +1,45 @@
+# 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)
+      "#{base}:top:#{type}:#{count}"
+    end
+  end
+end

data/lib/weathercock/scorable.rb

@@ -1,101 +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, decay_factor: nil, **window)
-        return Weathercock.config.redis.call("ZRANGE", "#{weathercock_base_key(event)}:total", 0, -1, "REV") if window.empty?
-
-        dest = weathercock_union(event, window, decay_factor: decay_factor)
-        Weathercock.config.redis.call("ZRANGE", dest, 0, -1, "REV")
-      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}"
+      def weathercock_scorer
+        @weathercock_scorer ||= Scorer.new(klass: self)
       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
+      def top(event, limit:, decay_factor: nil, **window)
+        weathercock_scorer.top(event, limit: limit, decay_factor: decay_factor, **window)
       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
-      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,96 @@
+# 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 { |id, score| [id.to_s, (score || "0").to_i] }
+    end
+
+    private
+
+    def union(event, window, decay_factor: nil)
+      base = @key_builder.base(event)
+      type, count = window.first
+      keys = @key_builder.window_keys(base, type, count)
+      dest = @key_builder.union_dest(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)
+      @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 = "0.1.0"
+  VERSION = "1.1.0"
 end

data/lib/weathercock.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "weathercock/version"
+require_relative "weathercock/key_builder"
+require_relative "weathercock/scorer"
+require_relative "weathercock/scorable"
 
 module Weathercock
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: weathercock
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Takafumi ONAKA
@@ -45,12 +45,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - 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
 homepage: https://github.com/onk/weathercock