sleek 0.0.1 → 0.0.2

data/lib/sleek/{base.rb → namespace.rb}

@@ -1,12 +1,12 @@
 module Sleek
-  class Base
-    attr_reader :namespace
+  class Namespace
+    attr_reader :name
 
     # Internal: Initialize Sleek with namespace.
     #
     # namespace - the Symbol namespace name.
-    def initialize(namespace)
-      @namespace = namespace
+    def initialize(name)
+      @name = name
     end
 
     # Public: Record an event.
@@ -14,12 +14,17 @@ module Sleek
     # bucket  - the String name of bucket.
     # payload - the Hash of event data.
     def record(bucket, payload)
-      Event.create_with_namespace(namespace, bucket, payload)
+      Event.create_with_namespace(name, bucket, payload)
     end
 
     # Public: Get `QueriesCollection` for the namespace.
     def queries
-      @queries ||= QueryCollection.new(namespace)
+      @queries ||= QueryCollection.new(self)
+    end
+
+    # Public: Delete the namespace.
+    def delete!
+      events.delete_all
     end
 
     # Public: Delete event bucket.
@@ -40,13 +45,13 @@ module Sleek
     # Internal: Get events associated with current namespace and,
     # optionally, specified bucket.
     def events(bucket = nil)
-      evts = Event.where(namespace: namespace)
+      evts = Event.where(namespace: name)
       evts = evts.where(bucket: bucket) if bucket.present?
       evts
     end
 
     def inspect
-      "#<Sleek::Base ns=#{namespace}>"
+      "#<Sleek::Namespace #{name}>"
     end
   end
 end

data/lib/sleek/queries.rb

@@ -1,5 +1,4 @@
 require 'sleek/queries/query'
-require 'sleek/queries/targetable'
 require 'sleek/queries/count'
 require 'sleek/queries/count_unique'
 require 'sleek/queries/minimum'

data/lib/sleek/queries/average.rb

@@ -11,7 +11,7 @@ module Sleek
     #   sleek.queries.average(:purchases, target_property: "total")
     #   # => 49_35
     class Average < Query
-      include Targetable
+      require_target_property!
 
       def perform(events)
         events.avg target_property

data/lib/sleek/queries/count_unique.rb

@@ -11,7 +11,7 @@ module Sleek
     #   sleek.queries.count_unique(:purchases, target_property: "customer.email")
     #   # => 4
     class CountUnique < Query
-      include Targetable
+      require_target_property!
 
       def perform(events)
         events.distinct(target_property).count

data/lib/sleek/queries/maximum.rb

@@ -11,7 +11,7 @@ module Sleek
     #   sleek.queries.maximum(:purchases, target_property: "total")
     #   # => 199_99
     class Maximum < Query
-      include Targetable
+      require_target_property!
 
       def perform(events)
         events.max target_property

data/lib/sleek/queries/minimum.rb

@@ -11,7 +11,7 @@ module Sleek
     #   sleek.queries.minimum(:purchases, target_property: "total")
     #   # => 19_99
     class Minimum < Query
-      include Targetable
+      require_target_property!
 
       def perform(events)
         events.min target_property

data/lib/sleek/queries/query.rb

@@ -1,11 +1,30 @@
 module Sleek
   module Queries
+    # Public: The query.
+    #
+    # Queries are performed on a set of events and usually return
+    # numeric values. You shouldn't be using Sleek::Queries::Query
+    # directly, instead, you should subclass it and define `#perform` on
+    # it, which takes an events criteria and does its job.
+    #
+    # Sleek::Queries::Query would take care of processing options,
+    # filtering events, handling series and groups.
+    #
+    # Examples
+    #
+    #   class SomeQuery < Query
+    #     def perform(events)
+    #       ...
+    #     end
+    #   end
     class Query
-      attr_reader :namespace, :bucket, :options
+      attr_reader :namespace, :bucket, :options, :timeframe
+
+      delegate :require_target_property?, to: 'self.class'
 
       # Internal: Initialize the query.
       #
-      # namespace - the Symbol namespace name.
+      # namespace - the Sleek::Namespace object.
       # bucket    - the String bucket name.
       # options   - the optional Hash of options.
       #             :timeframe - the optional timeframe description.
@@ -16,29 +35,35 @@ module Sleek
         @namespace = namespace
         @bucket = bucket
         @options = options
+        @timeframe = options[:timeframe]
 
-        raise ArgumentError, "options are invalid" unless valid_options?
+        raise ArgumentError, 'options are invalid' unless valid_options?
       end
 
       # Internal: Get Mongoid::Criteria for events to perform the query.
       #
       # time_range - the optional range of Time objects.
-      def events(time_range = time_range)
-        evts = Event.where(namespace: namespace, bucket: bucket)
-        evts = evts.between("s.t" => time_range) if time_range
+      def events
+        evts = namespace.events(bucket)
+        evts = evts.between('s.t' => timeframe) if timeframe?
         evts = apply_filters(evts) if filter?
+
+        if group_by.present?
+          evts = Sleek::GroupByCriteria.new(evts, "d.#{group_by}")
+        end
+
         evts
       end
 
       # Internal: Apply all the filters to the criteria.
       def apply_filters(criteria)
-        filters.inject(criteria) { |crit, filter| filter.apply(crit) }
+        filters.reduce(criteria) { |crit, filter| filter.apply(crit) }
       end
 
       # Internal: Get filters.
       def filters
         filters = options[:filter]
-        
+
         if filters.is_a?(Array) && filters.size == 3 && filters.none? { |f| f.is_a?(Array) }
           filters = [filters]
         elsif !filters.is_a?(Array) || !filters.all? { |f| f.is_a?(Array) && f.size == 3 }
@@ -48,22 +73,6 @@ module Sleek
         filters.map { |f| Sleek::Filter.new(*f) }
       end
 
-      # Internal: Get timeframe for the query.
-      #
-      # Returns nil if no timeframe was passed to initializer.
-      def timeframe
-        Sleek::Timeframe.new(options[:timeframe]) if timeframe?
-      end
-
-      # Internal: Get timeframe range.
-      def time_range
-        timeframe.try(:to_time_range)
-      end
-
-      def series
-        Sleek::Interval.new(options[:interval], timeframe).timeframes if series? && timeframe?
-      end
-
       # Internal: Check if options include filter.
       def filter?
         options[:filter].present?
@@ -71,23 +80,24 @@ module Sleek
 
       # Internal: Check if options include timeframe.
       def timeframe?
-        options[:timeframe].present?
+        timeframe.present?
       end
 
-      # Internal: Check if options include interval.
-      def series?
-        options[:interval].present?
+      # Internal: Get group_by property.
+      def group_by
+        options[:group_by]
+      end
+
+      # Internal: Get the target property.
+      def target_property
+        if options[:target_property].present?
+          "d.#{options[:target_property]}"
+        end
       end
 
       # Internal: Run the query.
       def run
-        if series?
-          series.map do |tf|
-            { timeframe: tf, value: perform(events(tf.to_time_range)) }
-          end
-        else
-          perform(events)
-        end
+        perform(events)
       end
 
       # Internal: Perform the query on a set of events.
@@ -97,8 +107,31 @@ module Sleek
 
       # Internal: Validate the options.
       def valid_options?
-        options.is_a?(Hash) && (filter? ? options[:filter].is_a?(Array) : true) &&
-          (series? ? timeframe? && series : true)
+        options.is_a?(Hash) &&
+          (filter? ? options[:filter].is_a?(Array) : true) &&
+          (require_target_property? ? options[:target_property].present? : true)
+      end
+
+      class << self
+        # Public: Indicate that the query requires target property.
+        #
+        # Examples
+        #
+        #   class SomeQuery < Query
+        #     require_target_property!
+        #
+        #     def perform(events)
+        #       ...
+        #     end
+        #   end
+        def require_target_property!
+          @require_target_property = true
+        end
+
+        # Public: Check if the query requires target property.
+        def require_target_property?
+          !!@require_target_property
+        end
       end
     end
   end

data/lib/sleek/queries/sum.rb

@@ -11,7 +11,7 @@ module Sleek
     #   sleek.queries.sum(:purchases, target_property: "total")
     #   # => 2_072_70
     class Sum < Query
-      include Targetable
+      require_target_property!
 
       def perform(events)
         events.sum target_property

data/lib/sleek/query_collection.rb

@@ -4,7 +4,7 @@ module Sleek
 
     # Inernal: Initialize query collection.
     #
-    # namespace - the Symbol namespace name.
+    # namespace - the Sleek::Namespace object.
     def initialize(namespace)
       @namespace = namespace
     end
@@ -14,12 +14,12 @@ module Sleek
       klass = "Sleek::Queries::#{name.to_s.camelize}".constantize
 
       define_method(name) do |bucket, options = {}|
-        klass.new(namespace, bucket, options).run
+        QueryCommand.new(klass, namespace, bucket, options).run
       end
     end
 
     def inspect
-      "#<Sleek::QueryCollection ns=#{namespace}>"
+      "#<Sleek::QueryCollection ns=#{namespace.name}>"
     end
   end
 end

data/lib/sleek/query_command.rb

@@ -0,0 +1,71 @@
+module Sleek
+  # Internal: A query command. It's primarily responsible for breaking a
+  # timeframe into intervals (if applicable), running the query on each
+  # sub-timeframe, and wrapping up a result.
+  class QueryCommand
+    attr_reader :klass, :namespace, :bucket, :options
+
+    # Internal: Initialize the query command.
+    #
+    # klass     - the Sleek::Queries::Query subclass.
+    # namespace - the Sleek::Namespace object.
+    # bucket    - the String bucket name.
+    # options   - the optional Hash of options. Everything but
+    #             :timeframe and :interval will be passed on to the
+    #             query class.
+    #             :timeframe - the optional timeframe description.
+    #             :timezone  - the optional TZ identifier.
+    #             :interval  - the optional interval description. If
+    #                          passed, requires that :timeframe is passed
+    #                          as well.
+    #
+    # Raises ArgumentError if :interval is passed but :timeframe is not.
+    def initialize(klass, namespace, bucket, options = {})
+      @klass = klass
+      @namespace = namespace
+      @bucket = bucket
+      @timeframe = options.delete(:timeframe)
+      @timezone = options.delete(:timezone)
+      @interval = options.delete(:interval)
+      @options = options
+
+      if @interval.present? && @timeframe.blank?
+        raise ArgumentError, 'interval requires timeframe'
+      end
+    end
+
+    # Internal: Check if options include interval.
+    def series?
+      @interval.present?
+    end
+
+    # Internal: Parse a time range from the timeframe description.
+    # description.
+    def timeframe
+      Sleek::Timeframe.to_range(@timeframe, @timezone) if @timeframe
+    end
+
+    # Internal: Split timeframe into sub-timeframes of interval.
+    def series
+      Sleek::Interval.new(@interval, timeframe).timeframes
+    end
+
+    # Internal: Instantiate a query object.
+    #
+    # timeframe - the time range.
+    def new_query(timeframe)
+      klass.new(namespace, bucket, options.merge(timeframe: timeframe))
+    end
+
+    # Internal: Run the query on each timeframe.
+    def run
+      if series?
+        series.map do |tf|
+          { timeframe: tf, value: new_query(tf).run }
+        end
+      else
+        new_query(timeframe).run
+      end
+    end
+  end
+end

data/lib/sleek/timeframe.rb

@@ -1,40 +1,6 @@
 module Sleek
   class Timeframe
-    # Internal: Initialize timeframe.
-    #
-    # timeframe - either a range of Time objects, an array of two Time
-    #             objects, or a special string.
-    #
-    # Possible special string format:
-    # (this|previous)_((\d+)_)?(minute|hour|day|week|month)s?
-    #
-    # Examples
-    #
-    #   Timeframe.new "this_2_days"
-    #
-    #   Timeframe.new "previous_hour"
-    def initialize(timeframe)
-      @timeframe = timeframe
-    end
-
-    # Public: Get timeframe start.
-    def start
-      to_time_range.begin
-    end
-
-    # Public: Get timeframe end.
-    def end
-      to_time_range.end
-    end
-
-    # Internal: Convert Timeframe instance to a range of Time objects.
-    def to_time_range
-      @range ||= self.class.to_range(@timeframe)
-    end
-
-    def inspect
-      "#<Sleek::Timeframe #{to_time_range}>"
-    end
+    REGEXP = /(this|previous)_((\d+)_)?(minute|hour|day|week|month)s?/
 
     class << self
       # Internal: Transform the object passed to Timeframe initializer
@@ -42,44 +8,71 @@ module Sleek
       #
       # timeframe - either a Range of Time objects, a two-element array
       #             of Time Objects, or a special string.
+      # timezone  - the optional String TZ identifier. See
+      #             `ActiveSupport::TimeZone`.
+      #
+      # Examples
+      #
+      #   Timeframe.to_range :this_2_days
+      #
+      #   Timeframe.to_range :previous_hour
+      #
+      #   Timeframe.to_range :this_day, timezone: 'US/Pacific'
       #
       # Raises ArgumentError if passed object can't be processed.
-      def to_range(timeframe)
+      def to_range(timeframe, timezone = nil)
         case timeframe
-        when Range
-          t = timeframe if timeframe.time_range?
-        when Array
-          t = timeframe.first..timeframe.last if timeframe.size == 2 && timeframe.count { |tf| tf.is_a?(Time) } == 2
+        when proc { |tf| tf.is_a?(Range) && tf.time_range? }
+          t = timeframe
+        when proc { |tf| tf.is_a?(Array) && tf.size == 2 && tf.count { |_tf| _tf.is_a?(Time) } == 2 }
+          t = timeframe.first..timeframe.last
         when String, Symbol
-          t = parse(timeframe.to_s)
+          t = parse(timeframe.to_s, timezone)
+        else
+          raise ArgumentError, "wrong timeframe - #{timeframe}"
         end
-
-        raise ArgumentError, "wrong timeframe" unless t
-        t
       end
 
       # Internal: Process timeframe string to make up a range.
       #
       # timeframe - the String matching
       #             (this|previous)_((\d+)_)?(minute|hour|day|week|month)s?
-      def parse(timeframe)
-        regexp = /(this|previous)_((\d+)_)?(minute|hour|day|week|month)s?/
-        _, category, _, number, interval = *timeframe.match(regexp)
+      # timezone  - the optional String TZ identifier. See
+      #             `ActiveSupport::TimeZone`.
+      def parse(timeframe, timezone = nil)
+        _, category, _, number, interval = *timeframe.match(REGEXP)
 
         unless category && interval
-          raise ArgumentError, "special timeframe string is malformed"
+          raise ArgumentError, 'special timeframe string is malformed'
         end
 
         number ||= 1
         number = number.to_i
 
-        end_point = Time.now.send("end_of_#{interval}").round
-        start_point = end_point - number.send(interval)
-
-        range = start_point..end_point
+        range = range_from_interval(interval, number, timezone)
         range = range - 1.send(interval) if category == 'previous'
         range
       end
+
+      # Internal: Create a time range from interval type & number of
+      # intervals.
+      #
+      # interval - the String interval type name. Valid values are
+      #            minute, hour, day, week, and month.
+      # number   - the Integer number of periods.
+      # timezone  - the optional String TZ identifier. See
+      #             `ActiveSupport::TimeZone`.
+      #
+      # Returns the range of TimeWithZone objects.
+      def range_from_interval(interval, number = 1, timezone = nil)
+        timezone ||= 'UTC'
+        now = ActiveSupport::TimeZone.new(timezone).now
+
+        end_point = now.send("end_of_#{interval}").round
+        start_point = end_point - number.send(interval)
+
+        start_point..end_point
+      end
     end
   end
 end