trackoid 0.1.1 → 0.1.2

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/trackoid/aggregates.rb

@@ -1,26 +1,74 @@
+# encoding: utf-8
 module Mongoid  #:nodoc:
-  module Tracking
-
+  module Tracking #:nodoc:
     module Aggregates
       # This module includes aggregate data extensions to Trackoid instances
       def self.included(base)
         base.class_eval do
           extend ClassMethods
-          include InstanceMethods
 
           class_inheritable_accessor :aggregate_fields, :aggregate_klass
-          self.aggregate_fields = []
+          self.aggregate_fields = {}
           self.aggregate_klass = nil
-#          delegate :aggregate_fields, :aggregate_klass, :to => "self.class"
+          delegate :aggregate_fields,
+                   :aggregate_klass,
+                   :aggregated?,
+                      :to => "self.class"
         end
       end
 
       module ClassMethods
-
+        # Defines an aggregate token to an already tracked model. It defines
+        # a new mongoid model named after the original model.
+        # 
+        # Example:
+        #
+        # <tt>class Page</tt>
+        # <tt>  include Mongoid::Document</tt>
+        # <tt>  include Mongoid::Document</tt>
+        # <tt>  track :visits</tt>
+        # <tt>  aggregate :browsers do |b|</tt>
+        # <tt>    b.split(" ").first</tt>
+        # <tt>  end</tt>
+        # <tt>end</tt>
+        #
+        # A new model is defined as <tt>class PageAggregates</tt>
+        #
+        # This model has the following structure:
+        # 
+        # <tt>belongs_to :page</tt>
+        # <tt>field :ns, :type => String</tt>
+        # <tt>field :key, :type => String</tt>
+        # <tt>index [:ns, :key], :unique => true</tt>
+        # <tt>track :[original_parent_tracking_data]</tt>
+        # <tt>track :...</tt>
+        #
+        # :ns is the "namespace". It's the name you put along the
+        # "aggregate :browsers" in the original model definition.
+        #
+        # :key is your aggregation key. This is the value you are required to
+        # return in the "aggregate" block.
+        #
+        # With the above structure, you can always query aggregates directly
+        # using Mongoid this way:
+        #
+        # <tt>TestModelAggregates.where(:ns => "browsers", :key => "explorer").first</tt>
+        #
+        # But you are encouraged to use Trackoid methods whenever possible.
+        #
         def aggregate(name, &block)
+          raise Errors::AggregationAlreadyDefined.new(self.name, name) if
+              aggregate_fields.has_key? name
+
           define_aggregate_model if aggregate_klass.nil?
-          has_many name.to_sym, :class_name => aggregate_klass.to_s
+          has_many_related internal_accessor_name(name), :class_name => aggregate_klass.to_s
           add_aggregate_field(name, block)
+          create_aggregation_accessors(name)
+        end
+
+        # Return true if this model has aggregated data.
+        def aggregated?
+          !aggregate_klass.nil?
         end
 
         protected
@@ -30,37 +78,62 @@ module Mongoid  #:nodoc:
           str.camelize
         end
 
+        def internal_accessor_name(name)
+          (name.to_s + "_accessor").to_sym
+        end
+
+        # Defines the aggregation model. It checks for class name conflicts
         def define_aggregate_model
           raise Errors::ClassAlreadyDefined.new(internal_aggregates_name) if foreign_class_defined
+          parent_name = self.name.underscore
           define_klass do
             include Mongoid::Document
             include Mongoid::Tracking
-            field :name, :type => String, :default => "Dummy Text"
-#            belongs_to :
+            
+            # Make the relation to the original class
+            belongs_to_related parent_name.to_sym, :class_name => parent_name.camelize
+
+            # Internal fields to track aggregation token and keys
+            field :ns,  :type => String
+            field :key, :type => String
+            index [[:ns, Mongo::ASCENDING], [:key, Mongo::ASCENDING]], :unique => true, :background => true
+
+            # Include parent tracking data.
+            parent_name.camelize.constantize.tracked_fields.each {|track_field| track track_field }
           end
           self.aggregate_klass = internal_aggregates_name.constantize
         end
-        
+
+        # Returns true if there is a class defined with the same name as our
+        # aggregate class.
         def foreign_class_defined
           Object.const_defined?(internal_aggregates_name.to_sym)
         end
 
+        # Adds the aggregate field to the array of aggregated fields.
         def add_aggregate_field(name, block)
-          aggregate_fields << { name => block }
+          aggregate_fields[name] = block
         end
 
+        # Defines the aggregation external class. This class is named after
+        # the original class model but with "Aggregates" appended.
+        # Example:  TestModel ==> TestModelAggregates
         def define_klass(&block)
-          # klass = Class.new Object, &block
-          klass = Object.const_set internal_aggregates_name, Class.new
+          klass = Object.const_set(internal_aggregates_name, Class.new)
           klass.class_eval(&block)
         end
 
-      end
-      
-      module InstanceMethods
-        def aggregated?
-          !self.class.aggregate_klass.nil?
+        def create_aggregation_accessors(name)
+          # Aggregation accessors in the model acts like a named scope
+          define_method(name) do |*args|
+            TrackerAggregates.new(self, name, args)
+          end
+
+          define_method("#{name}=") do
+            raise NoMethodError
+          end
         end
+
       end
       
     end
@@ -79,9 +152,10 @@ module Mongoid  #:nodoc:
     # end
     # 
     # 
-    # self.visits.inc("Google engine")
-    # 
-    # 
+    # self.visits(agg).inc
+    # self.visits.today
+    # self.visits.browsers.today
+    #
     # users
     #   { _id: 32334333, name:"pepe", visits_data:{} }
     # 

data/lib/trackoid/errors.rb

@@ -11,6 +11,15 @@ module Mongoid #:nodoc
       end
     end
 
+    class AggregationAlreadyDefined < RuntimeError
+      def initialize(klass, token)
+        @token = token
+      end
+      def message
+        "Aggregation '#{@token}' already defined for model #{klass}"
+      end
+    end
+
     class ModelNotSaved < RuntimeError; end
 
     class NotMongoid < RuntimeError; end

data/lib/trackoid/tracker.rb

@@ -3,19 +3,41 @@ module Mongoid  #:nodoc:
   module Tracking
     # This internal class handles all interaction for a track field.
     class Tracker
-      def initialize(owner, field)
+      
+      def initialize(owner, field, aggregate_data)
         @owner, @for = owner, field
-        @data = @owner.read_attribute(@for) || {}
+        @data = @owner.read_attribute(@for)
+        
+        # The following is needed if the "field" Mongoid definition for our
+        # internal tracking field does not include option ":default => {}"
+        if @data.nil?
+          @owner.write_attribute(@for, {})
+          @data = @owner.read_attribute(@for)
+        end
+
+        @aggregate_data = aggregate_data
       end
 
       # Update methods
       def add(how_much = 1, date = DateTime.now)
         raise Errors::ModelNotSaved, "Can't update a new record" if @owner.new_record?
-
         update_data(data_for(date) + how_much, date)
+
         @owner.collection.update( @owner._selector,
             { (how_much > 0 ? "$inc" : "$dec") => update_hash(how_much.abs, date) },
             :upsert => true)
+
+        return unless @owner.aggregated?
+
+        @owner.aggregate_fields.each do |(k,v)|
+          token = v.call(@aggregate_data)
+          fk = @owner.class.name.to_s.foreign_key.to_sym
+          selector = { fk => @owner.id, :ns => k, :key => token }
+
+          @owner.aggregate_klass.collection.update( selector,
+              { (how_much > 0 ? "$inc" : "$dec") => update_hash(how_much.abs, date) },
+              :upsert => true)
+        end
       end
 
       def inc(date = DateTime.now)
@@ -28,13 +50,13 @@ module Mongoid  #:nodoc:
 
       def set(how_much, date = DateTime.now)
         raise Errors::ModelNotSaved, "Can't update a new record" if @owner.new_record?
-
         update_data(how_much, date)
         @owner.collection.update( @owner._selector,
             { "$set" => update_hash(how_much, date) },
             :upsert => true)
       end
 
+
       # Access methods
       def today
         data_for(Date.today)
@@ -46,7 +68,6 @@ module Mongoid  #:nodoc:
 
       def last_days(how_much = 7)
         return [today] unless how_much > 0
-
         date, values = DateTime.now, []
         (date - how_much.abs + 1).step(date) {|d| values << data_for(d) }
         values
@@ -61,11 +82,13 @@ module Mongoid  #:nodoc:
       # Private methods
       private
       def data_for(date)
-        return 0 if @data[date.year.to_s].nil?
-        return 0 if @data[date.year.to_s][date.month.to_s].nil?
+        return 0 if @data.nil? ||
+                    @data[date.year.to_s].nil? ||
+                    @data[date.year.to_s][date.month.to_s].nil?
         @data[date.year.to_s][date.month.to_s][date.day.to_s] || 0
       end
 
+      # TODO: It should be a better way of updating a hash. :-)
       def update_data(value, date)
         if @data[date.year.to_s]
           if @data[date.year.to_s][date.month.to_s]
@@ -94,7 +117,6 @@ module Mongoid  #:nodoc:
         }
       end
 
-
       # WARNING: This is +only+ for debugging pourposes (rspec y tal)
       def _original_hash
         @data

data/lib/trackoid/tracker_aggregates.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+module Mongoid  #:nodoc:
+  module Tracking
+    # This internal class handles all interaction of an aggregation token.
+    class TrackerAggregates
+
+      def initialize(owner, token, key_selector)
+        @owner, @token = owner, token
+        @key = key_selector
+
+        @accessor = @owner.class.send(:internal_accessor_name, @token)
+        @selector = {:ns => @token}
+        @selector.merge!(:key => @key.first) if @key.first
+      end
+
+      def method_missing(name, *args, &block)
+        @criteria ||= @owner.send(@accessor).where(@selector)
+        
+        # Delegate all missing methods to the underlying Mongoid Criteria
+        return @criteria.send(name) unless @owner.tracked_fields.member?(name)
+        
+        # Otherwise, it's a track method, so process it
+        @criteria.collect {|x| x.send(name, *args, &block) }
+      end
+
+    end
+
+  end
+end

data/lib/trackoid/tracking.rb

@@ -20,13 +20,14 @@ module Mongoid #:nodoc:
 
     module ClassMethods
       # Adds analytics tracking for +name+. Adds a +'name'_data+ mongoid
-      # field as a Hash for tracking this information. Additionaly, makes
-      # this field hidden, so that the user can not mangle with the original
-      # field. This is necessary so that Mongoid does not "dirty" the field
-      # potentially overwriting the original data.
+      # field as a Hash for tracking this information. Additionaly, hiddes
+      # the field, so that the user can not mangle with the original one.
+      # This is necessary so that Mongoid does not "dirty" the field
+      # potentially overwriting the original data.
       def track(name)
         set_tracking_field(name)
         create_tracking_accessors(name)
+        update_aggregates(name) if aggregated?
       end
 
       protected
@@ -38,10 +39,10 @@ module Mongoid #:nodoc:
       # Configures the internal fields for tracking. Additionally also creates
       # an index for the internal tracking field.
       def set_tracking_field(name)
-        field internal_track_name(name), :type => Hash, :default => {}
-        # Shoul we make an index for this field?
+        field internal_track_name(name), :type => Hash    # , :default => {}
+        # Should we make an index for this field?
         index internal_track_name(name)
-        tracked_fields << internal_track_name(name)
+        tracked_fields << name.to_sym
       end
       
       # Creates the tracking field accessor and also disables the original
@@ -49,8 +50,8 @@ module Mongoid #:nodoc:
       # Mongoid fields ensures they doesn't get dirty, so Mongoid does not
       # overwrite old data.
       def create_tracking_accessors(name)
-        define_method("#{name}") do
-          Tracker.new(self, "#{name}_data".to_sym)
+        define_method("#{name}") do |*aggr|
+          Tracker.new(self, "#{name}_data".to_sym, aggr)
         end
 
         # Should we just "undef" this methods?
@@ -62,6 +63,17 @@ module Mongoid #:nodoc:
         define_method("#{name}_data=") do
           raise NoMethodError
         end
+        
+        # I think it's important to override also the #{name}_changed? so
+        # as to be sure Mongoid never mark this field as dirty.
+        define_method("#{name}_changed?") do
+          false
+        end
+      end
+      
+      # Updates the aggregated class for it to include a new tracking field
+      def update_aggregates(name)
+        aggregate_klass.track name
       end
       
     end

data/lib/trackoid.rb

@@ -5,6 +5,7 @@ gem "mongoid", ">= 1.9.0"
 require 'trackoid/errors'
 require 'trackoid/tracker'
 require 'trackoid/aggregates'
+require 'trackoid/tracker_aggregates'
 require 'trackoid/tracking'
 
 module Mongoid #:nodoc:

data/spec/aggregates_spec.rb

@@ -5,11 +5,15 @@ class TestModel
   include Mongoid::Tracking
 
   field :name   # Dummy field
+
+  # Note that references to "track" and "aggregate" in this test are mixed
+  # for testing pourposes. Trackoid does not make any difference in the
+  # declaration order of tracking fields and aggregate tokens.
   track :visits
+  aggregate :browsers do; "Mozilla".downcase; end
 
-  aggregate :browsers do
-    "Mozilla"
-  end
+  track :uniques
+  aggregate :referers do; "GoogleBot".downcase; end
 end
 
 class SecondTestModel
@@ -20,7 +24,7 @@ class SecondTestModel
   track :visits
 
   aggregate :browsers do
-    "Chrome"
+    "Chrome".downcase
   end
 end
 
@@ -39,30 +43,61 @@ describe Mongoid::Tracking::Aggregates do
   end
 
   it "should create a has_many relationship in the original model" do
-    @mock.class.method_defined?(:browsers).should be_true
+    # Note that due to ActiveSupport "class_inheritable_accessor" this method
+    # is available both as class method and instance method.
+    @mock.class.method_defined?(:browsers_accessor).should be_true
   end
 
-  it "should have the aggregates klass in a instance var" do
-    @mock.aggregate_klass == TestModelAggregates
+  it "should have the aggregates klass in a class/instance var" do
+    # Note that due to ActiveSupport "class_inheritable_accessor" this method
+    # is available both as class method and instance method.
+    @mock.class.aggregate_klass == TestModelAggregates
   end
 
-  it "should create an array in the class with all aggregate fields" do
-    @mock.class.aggregate_fields.map(&:keys).flatten.should == [ :browsers ]
+  it "should create a hash in the class with all aggregate fields" do
+    # Note that due to ActiveSupport "class_inheritable_accessor" this method
+    # is available both as class method and instance method.
+    @mock.class.aggregate_fields.keys.to_set.should == [ :browsers, :referers ].to_set
   end
 
   it "should create an array in the class with all aggregate fields even when monkey patching" do
     class TestModel
-      aggregate :referers do
-        "(none)"
+      aggregate :quarters do
+        "Q1"
       end
     end
-    @mock.class.aggregate_fields.map(&:keys).flatten.should == [ :browsers, :referers ]
+    @mock.class.aggregate_fields.keys.to_set.should == [ :browsers, :referers, :quarters ].to_set
+  end
+
+  it "the aggregated class should have the same tracking fields as the parent class" do
+    TestModelAggregates.tracked_fields.should == TestModel.tracked_fields
+  end
+
+  it "should raise error if we try to add an aggregation token twice" do
+    lambda {
+      class TestModel
+        aggregate :referers do
+          "(none)"
+        end
+      end
+    }.should raise_error Mongoid::Errors::AggregationAlreadyDefined
+  end
+
+  it "should have Mongoid accessors defined" do
+    tm = TestModel.create(:name => "Dummy")
+    tm.send(tm.class.send(:internal_accessor_name, "browsers")).class.should == Mongoid::Criteria
+    tm.send(tm.class.send(:internal_accessor_name, "referers")).class.should == Mongoid::Criteria
+    tm.send(tm.class.send(:internal_accessor_name, "quarters")).class.should == Mongoid::Criteria
   end
 
   it "should indicate this is an aggregated traking object with aggregated?" do
     @mock.aggregated?.should be_true
   end
 
+  it "should indicate this is an aggregated class with aggregated?" do
+    @mock.class.aggregated?.should be_true
+  end
+
   it "should raise error if already defined class with the same aggregated klass name" do
     lambda {
       class MockTestAggregates
@@ -115,4 +150,55 @@ describe Mongoid::Tracking::Aggregates do
     }.should raise_error Mongoid::Errors::ClassAlreadyDefined
   end
 
+  describe "when tracking a model with aggregation data" do
+
+    before(:all) do
+      TestModel.delete_all
+      TestModel.create(:name => "test")
+      @object_id = TestModel.first.id
+    end
+
+    before do
+      @mock = TestModel.find(@object_id)
+    end
+
+    it "calling an aggregation scope should return the appropiate class" do
+      @mock.browsers.class.should == Mongoid::Tracking::TrackerAggregates
+    end
+
+    it "should increment visits for all aggregated instances" do
+      @mock.visits("Aggregate data").inc
+      @mock.browsers.count.should == 1
+      @mock.referers.count.should == 1
+      @mock.quarters.count.should == 1
+    end
+
+    it "should increment visits for specific aggregation keys" do
+      @mock.browsers("mozilla").size.should == 1
+      @mock.referers("googlebot").size.should == 1
+      @mock.quarters("Q1").size.should == 1
+    end
+
+    it "should NOT increment visits for different aggregation keys" do
+      @mock.browsers("internet explorer").size.should == 0
+      @mock.referers("yahoo slurp").size.should == 0
+      @mock.quarters("Q2").size.should == 0
+    end
+
+    it "should have 1 in visits" do
+      tt = @mock.browsers.visits.collect {|v| v.last_days(7)}
+      tt.should == [[0, 0, 0, 0, 0, 0, 1]]
+    end
+
+    
+  end
+
+
+  # it "should print methods && their classes to stdout" do
+  #   TestModel.methods.sort.each {|x|
+  #     puts "#{x}"
+  #   }
+  #   should be_true
+  # end
+
 end

data/spec/spec_helper.rb

@@ -14,8 +14,9 @@ Mongoid.configure do |config|
   name = "trackoid_test"
   host = "localhost"
   port = "27017"
-  # config.master = Mongo::Connection.new(host, port, :logger => Logger.new(STDOUT)).db(name)
+#  config.master = Mongo::Connection.new(host, port, :logger => Logger.new(STDOUT)).db(name)
   config.master = Mongo::Connection.new.db(name)
+  config.use_object_ids = true
 end
 
 Spec::Runner.configure do |config|

data/spec/trackoid_spec.rb

@@ -49,7 +49,13 @@ describe Mongoid::Tracking do
     end
 
     it "should create a method for accesing the stats" do
-      @mock.respond_to?(:visits).should == true
+      @mock.respond_to?(:visits).should be_true
+    end
+
+    it "should respond 'false' to field_changed? method" do
+      # Ok, this test is not very relevant since it will return false even
+      # if Trackid does not override it.
+      @mock.visits_changed?.should be_false
     end
 
     it "should create a method for accesing the stats of the proper class" do
@@ -57,14 +63,14 @@ describe Mongoid::Tracking do
     end
 
     it "should create an array in the class with all tracking fields" do
-      @mock.class.tracked_fields.should == [ :visits_data ]
+      @mock.class.tracked_fields.should == [ :visits ]
     end
 
     it "should create an array in the class with all tracking fields even when monkey patching" do
       class Test
         track :something_else
       end
-      @mock.class.tracked_fields.should == [ :visits_data, :something_else_data ]
+      @mock.class.tracked_fields.should == [ :visits, :something_else ]
     end
 
     it "should not update stats when new record" do
@@ -211,8 +217,10 @@ describe Mongoid::Tracking do
       end
       tm = TestModel.first
       tm.something.today.should == 0
+      tm.something.inc
+      tm.something.today.should == 1
     end
-  
+
   end
 
 end

data/trackoid.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{trackoid}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jose Miguel Perez"]
-  s.date = %q{2010-06-04}
+  s.date = %q{2010-06-06}
   s.description = %q{Trackoid uses an embeddable approach to track analytics data using the poweful features of MongoDB for scalability}
   s.email = %q{josemiguel@perezruiz.com}
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
      "lib/trackoid/aggregates.rb",
      "lib/trackoid/errors.rb",
      "lib/trackoid/tracker.rb",
+     "lib/trackoid/tracker_aggregates.rb",
      "lib/trackoid/tracking.rb",
      "spec/aggregates_spec.rb",
      "spec/spec.opts",

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: trackoid
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: false
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Jose Miguel Perez
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-04 00:00:00 +02:00
+date: 2010-06-06 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -54,6 +54,7 @@ files:
 - lib/trackoid/aggregates.rb
 - lib/trackoid/errors.rb
 - lib/trackoid/tracker.rb
+- lib/trackoid/tracker_aggregates.rb
 - lib/trackoid/tracking.rb
 - spec/aggregates_spec.rb
 - spec/spec.opts