trackoid 0.3.8 → 0.4.0

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+Gemfile.lock
+
+## PROJECT::SPECIFIC

data/Gemfile

@@ -1,10 +1,6 @@
-source 'http://rubygems.org'
+source "http://rubygems.org"
 
-gem 'mongoid', '>= 2.1.0'
-
-group :development do
-  gem 'rake'
-  gem 'jeweler'
-  gem 'rspec', '>= 2.2.0'
-  gem 'mocha', '0.11.0'
-end
+# Declare your gem's dependencies in trackoid.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec

data/{README.rdoc → README.md}

@@ -1,23 +1,31 @@
-= trackoid
+# Trackoid
 
 Trackoid is an analytics tracking system made specifically for MongoDB using Mongoid as ORM.
 
-= *** IMPORTANT ***
+## IMPORTANT upgrade information
 
-Trackoid Version 0.3.0 changes the internal representation of tracking data. So <b>YOU WILL NOT SEE PREVIOUS DATA</b> when you update.
+**Trackoid Version 0.4.0** is updated to work with Mongoid 3. It's NOT backwards compatible with any previous version of Mongoid. A dependency on Ruby 1.9.x has also been added.
 
-Hopefully, due to the magic of MongoDB, data is <b>NOT LOST</b>. In fact it's never lost unless you delete it. :-) Just it's not visible right away.
+**Trackoid Version 0.3.0** changes the internal representation of tracking data. So **YOU WILL NOT SEE PREVIOUS DATA** when you update.
 
-See <b>Changes for TZ support</b> below for an explanation of changes. If you absolutely, desperately, dead or alive, need a migration, leave me a message and we can arrange a migration script.
+Hopefully, due to the magic of MongoDB, data is **NOT LOST**. In fact it's never lost unless you delete it. :-) _Just it's not visible right away_.
 
+See **Changes for TZ support** below for an explanation of changes in the internal representation of tracked data.
 
-= Requirements
+### Should I 'lock' the Trackoid version with Bundler?
+
+If you are new to Trackoid and don't know what I'm talking about **you're safe** upgrading from 0.4.x onwards.
+
+If you are having problems with Ruby 1.9.3 or not using Mongoid 3.x, probably you'll want to lock on 0.3.x, since 0.4.x *requires Mongoid 3.x** and hence, requires Ruby 1.9.3+.
+
+
+# Requirements
 
 Trackoid requires Mongoid, which obviously in turn requires MongoDB. Although you can only use Trackoid in Rails projects using Mongoid, it can easily be ported to MongoMapper or other ORM. You can also port it to work directly using MongoDB.
 
 Please feel free to fork and port to other libraries. However, Trackoid really requires MongoDB since it is build from scratch to take advantage of several MongoDB features (please let me know if you dare enough to port Trackoid into CouchDB or similar, I will be glad to know).
 
-= Using Trackoid to track analytics information for models
+# Using Trackoid to track analytics information for models
 
 Given the most obvious use for Trackoid, consider this example:
 
@@ -29,12 +37,12 @@ Given the most obvious use for Trackoid, consider this example:
 
       track :visits
     end
-    
+
 This class models a web page, and by using `track :visits` we add a `visits` field to track... well... visits. :-) Later, in out controller we can do:
 
     def view
       @page = WebPage.find(params[:webpage_id])
-      
+
       @page.visits.inc  # Increment a visit to this page
     end
 
@@ -52,11 +60,11 @@ Of course, you can also show visits in a time range:
       <% end %>
     </ul>
 
-== Not only visits...
+## Not only visits...
 
 Of course, you can use Trackoid to track all actions who require numeric analytics in a date frame.
 
-=== Prevent login to a control panel with a maximum login attemps
+### Prevent login to a control panel with a maximum login attemps
 
 You can track invalid logins so you can prevent login for a user when certain invalid login had been made. Imagine your login controller:
 
@@ -64,14 +72,14 @@ You can track invalid logins so you can prevent login for a user when certain in
     class User
       include Mongoid::Document
       include Mongoid::Tracking
-      
+
       track :failed_logins
     end
 
     # User controller
     def login
       user = User.find(params[:email])
-      
+
       # Stop login if failed attemps > 3
       redirect(root_path) if user.failed_logins.today > 3
 
@@ -92,7 +100,7 @@ Note that additionally you have the full failed login history for free. :-)
     @user.failed_logins.this_month
 
 
-=== Automatically saving a history of document changes
+### Automatically saving a history of document changes
 
 You can combine Trackoid with the power of callbacks to automatically track certain operations, for example modification of a document. This way you have a history of document changes.
 
@@ -112,7 +120,7 @@ You can combine Trackoid with the power of callbacks to automatically track cert
     end
 
 
-=== Track temperature history for a nuclear plant
+### Track temperature history for a nuclear plant
 
 Imagine you need a web service to track the temperature of all rooms of a nuclear plant. Now you have a simple method to do this:
 
@@ -120,7 +128,7 @@ Imagine you need a web service to track the temperature of all rooms of a nuclea
     class Room
       include Mongoid::Document
       include Mongoid::Tracking
-      
+
       track :temperature
     end
 
@@ -128,7 +136,7 @@ Imagine you need a web service to track the temperature of all rooms of a nuclea
     # Temperature controller
     def set_temperature_for_room
       @room = Room.find(params[:room_number])
-    
+
       @room.temperature.set(current_temperature)
     end
 
@@ -137,12 +145,12 @@ So, you are not restricted into incrementing or decrementing a value, you can al
     @room.temperature.last_days(30).max
 
 
-= How does it works?
+# How does it works?
 
 Trakoid works by embedding date tracking information into the models. The date tracking information is limited by a granularity of days, but you can use aggregates if you absolutely need hour or minutes granularity.
 
 
-== Scalability and performance
+## Scalability and performance
 
 Trackoid is made from the ground up to take advantage of the great scalability features of MongoDB. Trackoid uses "upsert" operations, bypassing Mongoid controllers so that it can be used in a distributed system without data loss. This is perfect for a cloud hosted SaaS application!
 
@@ -168,12 +176,12 @@ This way, the collection can receive multiple incremental operations without req
 
 In practice, we don't need visits information so fine grained, but it's good to take this into account.
 
-== Embedding tracking information into models
+## Embedding tracking information into models
 
 Tracking analytics data in SQL databases was historicaly saved into her own table, perhaps called `site_visits` with a relation to the sites table and each row saving an integer for each day.
 
     Table "site_visits"
-   
+
     SiteID  Date        Visits
     ------  ----------  ------
     1234    2010-05-01  34
@@ -184,7 +192,7 @@ With this schema, it's easy to get visits for a website using single SQL stateme
 
 Trackoid uses an embedding approach to tackle this. For the above examples, Trackoid would embedd a ruby Hash into the Site model. This means the tracking information is already saved "inside" the Site, and we don't have to reach the database for any date querying! Moreover, since the data retrieved with the accessor methods like "last_days", "this_month" and the like, are already arrays, we could use Array methods like sum, count, max, min, etc...
 
-== Memory implications
+## Memory implications
 
 Since storing all tracking information with the model implies we add additional information that can grow, and grow, and grow... You can be wondering yourself if this is a good idea. Yes, it's is, or at least I think so. Let me convice you...
 
@@ -195,7 +203,7 @@ A year full of statistical data takes only 2.8Kb, if you store integers. If your
 For comparison, this README is already 8.5Kb in size...
 
 
-= Changes for TZ support
+# Changes for TZ support
 
 Well, this is the time (no pun intended) to add TZ support to Trackoid.
 
@@ -203,7 +211,7 @@ The problem is that "today" is not the same "today" for everyone, so unless you
 
 But... Okay, given the fact that "today" is not the same "today" for everyone, this is the brand new Trackoid, with TZ support.
 
-== What has changed?
+## What has changed?
 
 In the surface, almost nothing, but internally there has been a major rewrite of the tracking code (the 'inc', 'set' methods) and the readers ('today', 'yesterday', etc). This is due to the changes I've made to the MongoDB structure of the tracking data.
 
@@ -275,7 +283,7 @@ The contents of every "day record" is another hash with 24 keys, one for each ho
       { :upsert => true, :safe => false }
     )
 
-== What "today" is it?
+## What "today" is it?
 
 All dates are saved in UTC. That means Trackoid returns a whole 24 hour block for "today" only where the TZ is exactly UTC/GMT (no offset). If you live in a country where there is an offset into UTC, Trackoid must read a whole block and some hours from the block before or after to build "your today".
 
@@ -292,11 +300,11 @@ Example: I live in GMT+0200 (Daylight saving in effect, or summer time), then if
         "02" : 30,
         ""
       }
-    
+
 This is a more graphical representation:
 
     Hours  00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23
-    ------ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --        
+    ------ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
     GMT+2: 00 00 00 XX 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
       UTC: --->  00 XX 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
            Shift up ---> 2 hours.
@@ -305,7 +313,7 @@ This is a more graphical representation:
 For timezones with a negative offset from UTC (Like PDT/PST) the process is reversed: UTC values are shifted down and holes filled with the following day.
 
 
-== How should I tell Trackoid how TZ to use?
+## How should I tell Trackoid how TZ to use?
 
 Piece of cake: Use the reader methods "today", "yesterday", "last_days(N)" and Trackoid will use the effective Time Zone of your Rails/Ruby application.
 
@@ -313,7 +321,8 @@ Trackoid will correctly translate dates for you (hopefully) if you pass a date t
 
 
 
-= Revision History
+# Revision History
+  0.3.8  - Fixed support for Ruby 1.9.3
 
   0.3.7  - Fixed support for Rails 3.1 and Mongoid 2.2
 
@@ -341,7 +350,7 @@ Trackoid will correctly translate dates for you (hopefully) if you pass a date t
 
          - Renamed the internal field of ReaderExtender to "total" so that
            converting to json automatically gives you:
-           
+
            {
              "total": <total value>
              "hours": [<hours array>]
@@ -356,13 +365,13 @@ Trackoid will correctly translate dates for you (hopefully) if you pass a date t
             * Reset does the same as "set" but also sets aggregate fields.
 
               Example:
-              
+
                 A) model.value(aggregate_data).set(5)
                 B) model.value(aggregate_data).reset(5)
-                
+
                 A will set "5" to the 'value' and to the aggregate.
                 B will set "5" to the 'value' and all aggregates.
-                
+
             * Erase resets the values in the mongo database. Note that this
               is completely different of doing 'reset(0)'. (With erase you
               can actually recall space from the database).
@@ -416,4 +425,3 @@ Trackoid will correctly translate dates for you (hopefully) if you pass a date t
 
   0.1.5  -  Added support for namespaced models and aggregations
          -  Enabled "set" operations on aggregates
-

data/Rakefile

@@ -1,40 +1,2 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "trackoid"
-    gem.summary = %Q{Trackoid is an easy scalable analytics tracker using MongoDB and Mongoid}
-    gem.description = %Q{Trackoid uses an embeddable approach to track analytics data using the poweful features of MongoDB for scalability}
-    gem.email = "josemiguel@perezruiz.com"
-    gem.homepage = "http://github.com/twoixter/trackoid"
-    gem.authors = ["Jose Miguel Perez"]
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
-end
-
-require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-end
-
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-task :default => :spec
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "trackoid #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/config/mongoid.yml

@@ -0,0 +1,8 @@
+test:
+  sessions:
+    default:
+      database: trackoid_test
+      hosts:
+        - 127.0.0.1:27017
+  options:
+    allow_dynamic_fields: false

data/lib/{trackoid → mongoid}/tracking.rb

@@ -10,13 +10,13 @@ module Mongoid #:nodoc:
         unless self.ancestors.include? Mongoid::Document
           raise Errors::NotMongoid, "Must be included in a Mongoid::Document"
         end
-        
+
         include Aggregates
         extend ClassMethods
-        
+
         class_attribute :tracked_fields
         self.tracked_fields = []
-        delegate :tracked_fields, :internal_track_name, :to => "self.class"
+        delegate :tracked_fields, :internal_track_name, to: "self.class"
       end
     end
 
@@ -41,15 +41,12 @@ 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 => {}
-
         # DONT make an index for this field. MongoDB indexes have limited
         # size and seems that this is not a good target for indexing.
         # index internal_track_name(name)
-
         tracked_fields << name
       end
-      
+
       # Creates the tracking field accessor and also disables the original
       # ones from Mongoid. Hidding here the original accessors for the
       # Mongoid fields ensures they doesn't get dirty, so Mongoid does not
@@ -58,29 +55,13 @@ module Mongoid #:nodoc:
         define_method(name) do |*aggr|
           Tracker.new(self, name, aggr)
         end
-
-        # Should we just "undef" this methods?
-        # They override the ones defined from Mongoid
-        define_method("#{name}_data") do
-          raise NoMethodError
-        end
-
-        define_method("#{name}_data=") do |m|
-          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
 
   end

data/lib/{trackoid → mongoid/tracking}/aggregates.rb

@@ -14,7 +14,7 @@ module Mongoid  #:nodoc:
           self.aggregate_fields = {}
           self.aggregate_klass = nil
           delegate :aggregate_fields, :aggregate_klass, :aggregated?,
-                   :to => "self.class"
+                   to: "self.class"
         end
       end
 
@@ -62,7 +62,7 @@ module Mongoid  #:nodoc:
           raise Errors::AggregationNameDeprecated.new(name) if DEPRECATED_TOKENS.include? name.to_s
 
           define_aggregate_model if aggregate_klass.nil?
-          has_many_related internal_accessor_name(name), :class_name => aggregate_klass.to_s
+          has_many internal_accessor_name(name), class_name: aggregate_klass.to_s
           add_aggregate_field(name, block)
           create_aggregation_accessors(name)
         end
@@ -90,32 +90,34 @@ module Mongoid  #:nodoc:
           end
 
           parent = self
+          
           define_klass do
             include Mongoid::Document
             include Mongoid::Tracking
 
             # Make the relation to the original class
-            belongs_to_related parent.name.demodulize.underscore.to_sym, :class_name => parent.name
+            belongs_to parent.name.demodulize.underscore.to_sym, class_name: parent.name
 
             # Internal fields to track aggregation token and keys
-            field :ns,  :type => String
-            field :key, :type => String
-            index [[parent.name.foreign_key.to_sym, Mongo::ASCENDING],
-                   [:ns, Mongo::ASCENDING],
-                   [:key, Mongo::ASCENDING]],
-                    :unique => true, :background => true
+            field :ns, type: String
+            field :key, type: String
+
+            index({ 
+              parent.name.foreign_key.to_sym => 1,
+              ns: 1,
+              key: 1
+            }, { unique: true, background: true })            
 
             # Include parent tracking data.
-            parent.tracked_fields.each {|track_field| track track_field }
+            parent.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?
-          # The following construct doesn't work with namespaced constants.
-          # Object.const_defined?(internal_aggregates_name.to_sym)
           internal_aggregates_name.constantize && true
         rescue NameError
           false
@@ -132,7 +134,9 @@ module Mongoid  #:nodoc:
         def define_klass(&block)
           scope = internal_aggregates_name.split('::')
           klass = scope.pop
-          scope = scope.inject(Object) {|scope, const_name| scope.const_get(const_name)}
+          scope = scope.inject(Object) do |scope, const_name| 
+            scope.const_get(const_name)
+          end
           klass = scope.const_set(klass, Class.new)
           klass.class_eval(&block)
         end