von 0.1.0 → 0.2.0

data/README.md

@@ -19,7 +19,7 @@ Von.increment('downloads')          # bumps the 'downloads' key 1 time
 Von.increment('downloads:app123')   # bumps the 'downloads:app123' key 1 time AND the 'downloads' key 1 time
 ```
 
-## Time Period Grouping and Limiting
+## Tracking Time Periods
 
 By default Von will only bump a "total" counter for the given key. This is great, but what makes Von really useful is that it can be configured to group certain keys by hour, day, week, month, and year. And you can set limits on how many of each you want to keep around. Here's how it works:
 
@@ -34,23 +34,64 @@ Von.configure do |config|
 end
 ```
 
-### Incrementing Time Periods
+## Tracking the Current Time Period
 
-Once you've configured the keys you want to use Time Periods on, you just increment them like normal, Von handles the rest.
+If just wanna track stats on the current minute/hour/day/week/etc, you can set that up pretty easily with Von:
+
+```ruby
+Von.configure do |config|
+    # Track downloads stats for the current hour
+    config.counter 'downloads', :current => :hour
+
+    # Track page views for the current day and week
+    config.counter 'page-views', :current => [ :day, :week ]
+end
+```
+
+## Tracking "Bests"
+
+Time periods are pretty cool, but sometimes you wanna know when you did your best. You can track these with Von as well:
+
+```ruby
+Von.configure do |config|
+    # Track the best day for downloads
+    config.counter 'downloads', :best => :day
+
+    # Track the best hour and week for page views
+    config.counter 'page-views', :best => [ :hour, :week ]
+end
+```
+
+## Incrementing
+
+Once you've configured the keys you don't have to do anything special, just increment the key, Von will handle this rest.
 
 ```ruby
 Von.increment('downloads')
 Von.increment('uploads')
+Von.increment('page-views')
 ```
 
 ## Getting Stats
 
 ```ruby
 # get the total downloads (returns an Integer)
-Von.count('downloads')  #=> 4
+Von.count('downloads').total       #=> 4
+
 # get the monthly counts (returns an Array of Hashes)
-Von.count('uploads', :monthly)  #=> [ { '2012-03 => 3}, { '2013-04' => 1 }, { '2013-05' => 0 }]
+Von.count('uploads').per(:month)   #=> [ { :timestamp => '2012-03', :count => 3 }, { :timestamp => '2013-04', :count => 1 }, { :timestamp => '2013-05', :count => 0 }]
+
+# get the download stats for the hour
+Von.count('downloads').this(:hour)          #=> 10
+# or
+Von.count('downloads').current(:hour)       #=> 10
+
+# get the page-views for today
+Von.count('page-views').today               #=> 78
+Von.count('page-views').current(:day)       #=> 78
 
+# get the best day for downloads (returns a Hash)
+Von.count('downloads').best(:day)  #=> { :timestamp => '2012-03-01', :count => 10 }
 ```
 
 One nice thing to note, if you're counting a time period and there wasn't a value stored for the particular hour/day/week/etc, it'll be populated with a zero, this ensures that if you want 30 days of stats, you get 30 days of stats.

data/Rakefile

@@ -4,7 +4,7 @@ require 'bundler/gem_tasks'
 
 Rake::TestTask.new do |t|
     t.libs << 'test'
-    t.test_files = FileList['test/*_test.rb']
+    t.test_files = FileList['test/**/*_test.rb']
 end
 
 task :default => :test

data/lib/von.rb

@@ -2,11 +2,18 @@ require 'redis'
 require 'active_support/time'
 
 require 'von/config'
-require 'von/counter'
 require 'von/period'
+require 'von/counter'
+require 'von/counters/commands'
+require 'von/counters/total'
+require 'von/counters/period'
+require 'von/counters/best'
+require 'von/counters/current'
 require 'von/version'
 
 module Von
+  PARENT_REGEX = /:?[^:]+\z/
+
   def self.connection
     @connection ||= config.redis
   end
@@ -20,16 +27,46 @@ module Von
   end
 
   def self.increment(field)
-    Counter.increment(field)
+    parents = field.to_s.sub(PARENT_REGEX, '')
+    total   = increment_counts_for(field)
+
+    until parents.empty? do
+      increment_counts_for(parents)
+      parents.sub!(PARENT_REGEX, '')
+    end
+
+    total
   rescue Redis::BaseError => e
     raise e if config.raise_connection_errors
   end
 
-  def self.count(field, period = nil)
-    Counter.count(field, period)
+  def self.increment_counts_for(field)
+    counter = Counters::Total.new(field)
+    total   = counter.increment
+
+    if config.periods_defined_for_counter?(counter)
+      periods = config.periods[counter.field]
+      Counters::Period.new(counter.field, periods).increment
+    end
+
+    if config.bests_defined_for_counter?(counter)
+      periods = config.bests[counter.field]
+      Counters::Best.new(counter.field, periods).increment
+    end
+
+    if config.currents_defined_for_counter?(counter)
+      periods = config.currents[counter.field]
+      Counters::Current.new(counter.field, periods).increment
+    end
+
+    total
+  end
+
+  def self.count(field)
+    Counter.new(field)
   rescue Redis::BaseError => e
     raise e if config.raise_connection_errors
   end
 
   config.init!
-end
+end

data/lib/von/config.rb

@@ -11,26 +11,33 @@ module Von
     attr_accessor :weekly_format
     attr_accessor :daily_format
     attr_accessor :hourly_format
+    attr_accessor :minutely_format
 
-    attr_reader  :periods
+    attr_reader :periods
+    attr_reader :bests
+    attr_reader :currents
 
     def init!
-      @counter_options = {}
-      @periods         = {}
+      @periods  = {}
+      @bests    = {}
+      @currents = {}
+      @totals   = {}
       # all keys are prefixed with this namespace
       self.namespace = 'von'
       # rescue Redis connection errors
       self.raise_connection_errors = false
       # 2013
-      self.yearly_format  = '%Y'
+      self.yearly_format   = '%Y'
       # 2013-01
-      self.monthly_format = '%Y-%m'
+      self.monthly_format  = '%Y-%m'
       # 2013-01-02
-      self.weekly_format  = '%Y-%m-%d'
+      self.weekly_format   = '%Y-%m-%d'
       # 2013-01-02
-      self.daily_format   = '%Y-%m-%d'
+      self.daily_format    = '%Y-%m-%d'
       # 2013-01-02 12:00
-      self.hourly_format  = '%Y-%m-%d %H:00'
+      self.hourly_format   = '%Y-%m-%d %H:00'
+      # 2013-01-02 12:05
+      self.minutely_format = '%Y-%m-%d %H:%M'
     end
 
     # Set the Redis connection to use
@@ -54,28 +61,51 @@ module Von
     # Configure options for given Counter. Configures length of given time period
     # and any other options for the Counter
     def counter(field, options = {})
-      options.each do |key, value|
-        if Period::AVAILABLE_PERIODS.include?(key)
-          @periods[field.to_sym] ||= {}
-          @periods[field.to_sym][key.to_sym] = Period.new(field, key, value)
-          options.delete(key)
-        end
+      field = field.to_sym
+      options.each do |option, value|
+        set_period(field, option, value) if Period.exists?(option)
+        set_best(field, value) if option == :best
+        set_current(field, value) if option == :current
       end
+    end
+
+    # Returns a True if a period is defined for the
+    # given Counter
+    # TODO: these should just take the key, will fix when renaming field
+    def periods_defined_for_counter?(counter)
+      @periods.has_key?(counter.field)
+    end
+
+    # Returns a True if a best is defined for the
+    # given counter
+    def bests_defined_for_counter?(counter)
+      @bests.has_key?(counter.field)
+    end
+
+    # Returns a True if a current is defined for the
+    # given counter
+    def currents_defined_for_counter?(counter)
+      @currents.has_key?(counter.field)
+    end
+
+    private
 
-      @counter_options[field.to_sym] = options
+    def set_period(field, period, length)
+      @periods[field] ||= []
+      @periods[field] << Period.new(period, length)
     end
 
-    # Returns a True if a Period is defined for the
-    # given period identifier and the period has a length
-    # False if not
-    def period_defined_for?(key, period)
-      @periods.has_key?(key) && @periods[key].has_key?(period)
+    def set_best(field, time_unit)
+      @bests[field] = [ time_unit ].flatten.map { |u|
+        Period.new(u)
+      }
     end
 
-    # TODO: rename
-    def counter_options(field)
-      @counter_options[field.to_sym] ||= {}
+    def set_current(field, time_unit)
+      @currents[field] = [ time_unit ].flatten.map { |u|
+        Period.new(u)
+      }
     end
 
   end
-end
+end

data/lib/von/counter.rb

@@ -1,112 +1,70 @@
 module Von
   class Counter
-    PARENT_REGEX = /:?[^:]+\z/
 
-    # Initialize a new Counter
-    #
-    # field - counter field name
     def initialize(field)
       @field = field.to_sym
     end
 
-    # Returns options specified in config for this Counter
-    def options
-      @options ||= Von.config.counter_options(@field)
+    def to_s
+      Counters::Total.new(@field).count.to_s
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Returns the Redis hash key used for storing counts for this Counter
-    def hash_key
-      @hash_key ||= "#{Von.config.namespace}:counters:#{@field}"
+    def to_i
+      Counters::Total.new(@field).count
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Increment the total count for this Counter
-    # If the key has time periods specified, increment those.
-    #
-    # Returns the Integer total for the key
-    def increment
-      total = Von.connection.hincrby(hash_key, 'total', 1)
-
-      increment_periods
-
-      total
+    def total
+      Counters::Total.new(@field).count
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Increment periods associated with this key
-    def increment_periods
-      return unless Von.config.periods.has_key?(@field.to_sym)
+    def per(unit)
+      periods = Von.config.periods[@field]
 
-      Von.config.periods[@field.to_sym].each do |key, period|
-        Von.connection.hincrby(period.hash_key, period.field, 1)
-        unless Von.connection.lrange(period.list_key, 0, -1).include?(period.field)
-          Von.connection.rpush(period.list_key, period.field)
-        end
-
-        if Von.connection.llen(period.list_key) > period.length
-          expired_counter = Von.connection.lpop(period.list_key)
-          Von.connection.hdel(period.hash_key, expired_counter)
-        end
+      if !Period.time_unit_exists?(unit)
+        raise ArgumentError, "`#{unit}' is an unknown time unit"
+      else
+        Counters::Period.new(@field, periods).count(unit)
       end
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Increment the Redis count for this Counter.
-    # If the key has parents, increment them as well.
-    #
-    # Returns the Integer total for the key
-    def self.increment(field)
-      total   = Counter.new(field).increment
-      parents = field.sub(PARENT_REGEX, '')
+    def best(unit)
+      periods = Von.config.bests[@field]
 
-      until parents.empty? do
-        Counter.new(parents).increment
-        parents.sub!(PARENT_REGEX, '')
+      if !Period.time_unit_exists?(unit)
+        raise ArgumentError, "`#{unit}' is an unknown time unit"
+      else
+        Counters::Best.new(@field, periods).count(unit)
       end
-
-      total
-    end
-
-    # Count the "total" field for this Counter.
-    #
-    # Returns an Integer count
-    def count
-      Von.connection.hget(hash_key, 'total')
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Count the fields for the given time period for this Counter.
-    #
-    # Returns an Array of Hashes representing the count
-    def count_period(period)
-      return unless Von.config.period_defined_for?(@field, period)
-
-      _counts   = []
-      _period   = Von.config.periods[@field][period]
-      now       = DateTime.now.beginning_of_hour
+    def this(unit)
+      periods = Von.config.currents[@field]
 
-      _period.length.times do
-        this_period = now.strftime(_period.format)
-        _counts.unshift(this_period)
-        now = _period.hours? ? now.ago(3600) : now.send(:"prev_#{_period.time_unit}")
+      if !Period.time_unit_exists?(unit)
+        raise ArgumentError, "`#{unit}' is an unknown time unit"
+      else
+        Counters::Current.new(@field, periods).count(unit)
       end
-
-      keys = Von.connection.hgetall("#{hash_key}:#{period}")
-      _counts.map { |date| { date => keys.fetch(date, 0) }}
+    rescue Redis::BaseError => e
+      raise e if Von.config.raise_connection_errors
     end
 
-    # Lookup the count for this Counter in Redis.
-    # If a Period argument is given we lookup the count for
-    # all of the possible units (not expired), zeroing ones that
-    # aren't set in Redis already.
-    #
-    # period - A Period to lookup
-    #
-    # Returns an Integer representing the count or an Array of counts.
-    def self.count(field, period = nil)
-      counter = Counter.new(field)
+    alias :current :this
 
-      if period.nil?
-        counter.count
-      else
-        counter.count_period(period.to_sym)
-      end
+    def today
+      periods = Von.config.currents[@field]
+
+      Counters::Current.new(@field, periods).count(:day)
     end
 
   end

data/lib/von/counters/best.rb

@@ -0,0 +1,68 @@
+module Von
+  module Counters
+    class Best
+      include Von::Counters::Commands
+
+      def initialize(field, periods = nil)
+        @field   = field.to_sym
+        @periods = periods || []
+      end
+
+      def hash_key
+        @hash_key ||= "#{Von.config.namespace}:counters:bests:#{@field}"
+      end
+
+      def best_total(time_unit)
+        hget("#{hash_key}:#{time_unit}:best", 'total').to_i
+      end
+
+      def best_timestamp(time_unit)
+        hget("#{hash_key}:#{time_unit}:best", 'timestamp')
+      end
+
+      def current_total(time_unit)
+        hget("#{hash_key}:#{time_unit}:current", 'total').to_i
+      end
+
+      def current_timestamp(time_unit)
+        hget("#{hash_key}:#{time_unit}:current", 'timestamp')
+      end
+
+      def increment
+        return if @periods.empty?
+
+        @periods.each do |period|
+          _current_timestamp = current_timestamp(period.time_unit)
+          _current_total     = current_total(period.time_unit)
+
+          if period.timestamp != _current_timestamp
+            # changing current period
+            hset("#{hash_key}:#{period.time_unit}:current", 'total', 1)
+            hset("#{hash_key}:#{period.time_unit}:current", 'timestamp', period.timestamp)
+
+            if best_total(period) < _current_total
+              hset("#{hash_key}:#{period.time_unit}:best", 'total', _current_total)
+              hset("#{hash_key}:#{period.time_unit}:best", 'timestamp', _current_timestamp)
+            end
+          else
+            hincrby("#{hash_key}:#{period.time_unit}:current", 'total', 1)
+          end
+        end
+      end
+
+      def count(time_unit)
+        _current_timestamp = current_timestamp(time_unit)
+        _current_total     = current_total(time_unit)
+        _best_timestamp    = best_timestamp(time_unit)
+        _best_total        = best_total(time_unit)
+
+        if _current_total > _best_total
+          { :timestamp => _current_timestamp, :count => _current_total }
+        else
+          { :timestamp => _best_timestamp, :count => _best_total }
+        end
+      end
+
+    end
+  end
+end