groupdate 4.3.0 → 5.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c661470fa1d3e85d4cff490be69845b175f5c095956ae674bda74e25e8713d1e
-  data.tar.gz: d2f4a2adb3dec4d73fdfc36302514c7c9c051766bb2703057b4074e3f480223c
+  metadata.gz: 05ffc10283f2de5fa74bacff7a6368636f62e8ddb263dd33d191502c0b418edc
+  data.tar.gz: 887827ef96299b9916f97e554706e670e83c99dad2522755c760348bdd3077cf
 SHA512:
-  metadata.gz: f7e3309e4f687cb88839c23d07f6ad9dce57ee3f8f18c335d695d79fe4c0d7fe4e236d1362071180ba07daf3eb6edd62ace05f4d15e0f4392c2dc48e81139c17
-  data.tar.gz: 2b1682b63429bb482b01cb8f50a5bd0ab03a0677b9a806244c7d26054579611b1678f056c713d23278cd5cd3e8616def5c77d0897caccda7c5a6d297e4eaa863
+  metadata.gz: 5d8cdf01f590ff7575539e39e9207e14eac7bd04417483fe453a7f1fb281e9bf9869678fbb7e2cc2381ccdfb678f47c6ca82b644ea291149ed48fdfba61963a3
+  data.tar.gz: 190dd79d14e7b00a7aa5492a46cfa18d50b56af08bd489fc8e68560530e0edb91a124932a24444116dd0cda09c926834c9ac33ed2b4b8c5117601e24b2ee0eac

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## 5.2.2 (2021-02-08)
+
+- Added support for `nil..nil` ranges in `range` option
+
+## 5.2.1 (2020-09-09)
+
+- Improved error message for invalid ranges
+- Fixed bug with date string ranges
+
+## 5.2.0 (2020-09-07)
+
+- Added warning for non-attribute argument
+- Added support for beginless and endless ranges in `range` option
+
+## 5.1.0 (2020-07-30)
+
+- Added `n` option to minute and second for custom durations
+
+## 5.0.0 (2020-02-18)
+
+- Added support for `week_start` for SQLite
+- Added support for full weekday names
+- Made `day_start` behavior consistent between Active Record and enumerable
+- Made `last` option extend to end of current period
+- Raise error when `day_start` and `week_start` passed to unsupported methods
+- The `day_start` option no longer applies to shorter periods
+- Fixed `inconsistent time zone info` errors around DST with MySQL and PostgreSQL
+- Improved performance of `format` option
+- Removed deprecated positional arguments for time zone and range
+- Dropped support for `mysql` gem (last release was 2013)
+
 ## 4.3.0 (2019-12-26)
 
 - Fixed error with empty results in Ruby 2.7

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2019 Andrew Kane
+Copyright (c) 2013-2021 Andrew Kane
 
 MIT License
 

data/README.md

@@ -15,7 +15,7 @@ Supports PostgreSQL, MySQL, and Redshift, plus arrays and hashes (and limited su
 
 :cupid: Goes hand in hand with [Chartkick](https://www.chartkick.com)
 
-[![Build Status](https://travis-ci.org/ankane/groupdate.svg?branch=master)](https://travis-ci.org/ankane/groupdate)
+[![Build Status](https://github.com/ankane/groupdate/workflows/build/badge.svg?branch=master)](https://github.com/ankane/groupdate/actions)
 
 ## Installation
 
@@ -32,9 +32,9 @@ For MySQL and SQLite, also follow [these instructions](#additional-instructions)
 ```ruby
 User.group_by_day(:created_at).count
 # {
-#   Sat, 28 May 2016 => 50,
-#   Sun, 29 May 2016 => 100,
-#   Mon, 30 May 2016 => 34
+#   Sat, 24 May 2020 => 50,
+#   Sun, 25 May 2020 => 100,
+#   Mon, 26 May 2020 => 34
 # }
 ```
 
@@ -53,13 +53,14 @@ You can group by:
 
 and
 
+- minute_of_hour
 - hour_of_day
 - day_of_week (Sunday = 0, Monday = 1, etc)
 - day_of_month
 - day_of_year
 - month_of_year
 
-Use it anywhere you can use `group`. Works with `count`, `sum`, `minimum`, `maximum`, and `average`. For `median`, check out [ActiveMedian](https://github.com/ankane/active_median).
+Use it anywhere you can use `group`. Works with `count`, `sum`, `minimum`, `maximum`, and `average`. For `median` and `percentile`, check out [ActiveMedian](https://github.com/ankane/active_median).
 
 ### Time Zones
 
@@ -74,9 +75,9 @@ or
 ```ruby
 User.group_by_week(:created_at, time_zone: "Pacific Time (US & Canada)").count
 # {
-#   Sun, 06 Mar 2016 => 70,
-#   Sun, 13 Mar 2016 => 54,
-#   Sun, 20 Mar 2016 => 80
+#   Sun, 08 Mar 2020 => 70,
+#   Sun, 15 Mar 2020 => 54,
+#   Sun, 22 Mar 2020 => 80
 # }
 ```
 
@@ -87,13 +88,13 @@ Time zone objects also work. To see a list of available time zones in Rails, run
 Weeks start on Sunday by default. Change this with:
 
 ```ruby
-Groupdate.week_start = :mon # first three letters of day
+Groupdate.week_start = :monday
 ```
 
 or
 
 ```ruby
-User.group_by_week(:created_at, week_start: :mon).count
+User.group_by_week(:created_at, week_start: :monday).count
 ```
 
 ### Day Start
@@ -147,8 +148,8 @@ To get keys in a different format, use:
 ```ruby
 User.group_by_month(:created_at, format: "%b %Y").count
 # {
-#   "Jan 2015" => 10
-#   "Feb 2015" => 12
+#   "Jan 2020" => 10
+#   "Feb 2020" => 12
 # }
 ```
 
@@ -193,6 +194,14 @@ User.group_by_period(params[:period], :created_at, permit: ["day", "week"]).coun
 
 Raises an `ArgumentError` for unpermitted periods.
 
+### Custom Duration
+
+To group by a specific number of minutes or seconds, use:
+
+```ruby
+User.group_by_minute(:created_at, n: 10).count # 10 minutes
+```
+
 ### Date Columns
 
 If grouping on date columns which don’t need time zone conversion, use:
@@ -263,7 +272,7 @@ It should return the time instead of `NULL`.
 Groupdate has limited support for SQLite.
 
 - No time zone support
-- No `day_start` or `week_start` options
+- No `day_start` option
 - No `group_by_quarter` method
 
 If your application’s time zone is set to something other than `Etc/UTC` (the default), create an initializer with:
@@ -274,36 +283,18 @@ Groupdate.time_zone = false
 
 ## Upgrading
 
-### 4.0
-
-Groupdate 4.0 brings a number of improvements. Here are a few to be aware of:
+### 5.0
 
-- `group_by` methods return an `ActiveRecord::Relation` instead of a `Groupdate::Series`
-- Invalid options now throw an `ArgumentError`
-- `week_start` now affects `day_of_week`
-- Custom calculation methods are supported by default
+Groupdate 5.0 brings a number of improvements. Here are a few to be aware of:
 
-### 3.0
-
-Groupdate 3.0 brings a number of improvements. Here are a few to be aware of:
-
-- `Date` objects are now returned for day, week, month, quarter, and year by default. Use `dates: false` for the previous behavior, or change this globally with `Groupdate.dates = false`.
-- Array and hash methods no longer return the entire series by default. Use `series: true` for the previous behavior.
-- The `series: false` option now returns the correct type and order, and plays nicely with other options.
-
-### 2.0
-
-Groupdate 2.0 brings a number of improvements. Here are two things to be aware of:
-
-- the entire series is returned by default
-- `ActiveSupport::TimeWithZone` keys are now returned for every database adapter - adapters previously returned `Time` or `String` keys
+- The `week_start` option is now supported for SQLite
+- The `day_start` option is now consistent between Active Record and enumerable
+- Deprecated positional arguments for time zone and range have been removed
 
 ## History
 
 View the [changelog](https://github.com/ankane/groupdate/blob/master/CHANGELOG.md)
 
-Groupdate follows [Semantic Versioning](https://semver.org/)
-
 ## Contributing
 
 Everyone is encouraged to help improve this project. Here are a few ways you can help:

data/lib/groupdate.rb

@@ -1,9 +1,18 @@
+# dependencies
 require "active_support/core_ext/module/attribute_accessors"
 require "active_support/time"
-require "groupdate/version"
-require "groupdate/relation_builder"
-require "groupdate/series_builder"
+
+# modules
 require "groupdate/magic"
+require "groupdate/series_builder"
+require "groupdate/version"
+
+# adapters
+require "groupdate/adapters/base_adapter"
+require "groupdate/adapters/mysql_adapter"
+require "groupdate/adapters/postgresql_adapter"
+require "groupdate/adapters/redshift_adapter"
+require "groupdate/adapters/sqlite_adapter"
 
 module Groupdate
   class Error < RuntimeError; end
@@ -12,7 +21,7 @@ module Groupdate
   METHODS = PERIODS.map { |v| :"group_by_#{v}" } + [:group_by_period]
 
   mattr_accessor :week_start, :day_start, :time_zone, :dates
-  self.week_start = :sun
+  self.week_start = :sunday
   self.day_start = 0
   self.dates = true
 
@@ -23,8 +32,23 @@ module Groupdate
     end
     result
   end
+
+  def self.adapters
+    @adapters ||= {}
+  end
+
+  def self.register_adapter(name, adapter)
+    Array(name).each do |n|
+      adapters[n] = adapter
+    end
+  end
 end
 
+Groupdate.register_adapter ["Mysql2", "Mysql2Spatial", "Mysql2Rgeo"], Groupdate::Adapters::MySQLAdapter
+Groupdate.register_adapter ["PostgreSQL", "PostGIS"], Groupdate::Adapters::PostgreSQLAdapter
+Groupdate.register_adapter "Redshift", Groupdate::Adapters::RedshiftAdapter
+Groupdate.register_adapter "SQLite", Groupdate::Adapters::SQLiteAdapter
+
 require "groupdate/enumerable"
 
 ActiveSupport.on_load(:active_record) do

data/lib/groupdate/adapters/base_adapter.rb

@@ -0,0 +1,70 @@
+module Groupdate
+  module Adapters
+    class BaseAdapter
+      attr_reader :period, :column, :day_start, :week_start, :n_seconds
+
+      def initialize(relation, column:, period:, time_zone:, time_range:, week_start:, day_start:, n_seconds:)
+        # very important
+        column = validate_column(column)
+
+        @relation = relation
+        @column = resolve_column(relation, column)
+        @period = period
+        @time_zone = time_zone
+        @time_range = time_range
+        @week_start = week_start
+        @day_start = day_start
+        @n_seconds = n_seconds
+
+        if relation.default_timezone == :local
+          raise Groupdate::Error, "ActiveRecord::Base.default_timezone must be :utc to use Groupdate"
+        end
+      end
+
+      def generate
+        @relation.group(group_clause).where(*where_clause)
+      end
+
+      private
+
+      def where_clause
+        if @time_range.is_a?(Range)
+          if @time_range.end
+            op = @time_range.exclude_end? ? "<" : "<="
+            if @time_range.begin
+              ["#{column} >= ? AND #{column} #{op} ?", @time_range.begin, @time_range.end]
+            else
+              ["#{column} #{op} ?", @time_range.end]
+            end
+          else
+            ["#{column} >= ?", @time_range.begin]
+          end
+        else
+          ["#{column} IS NOT NULL"]
+        end
+      end
+
+      # basic version of Active Record disallow_raw_sql!
+      # symbol = column (safe), Arel node = SQL (safe), other = untrusted
+      # matches table.column and column
+      def validate_column(column)
+        unless column.is_a?(Symbol) || column.is_a?(Arel::Nodes::SqlLiteral)
+          column = column.to_s
+          unless /\A\w+(\.\w+)?\z/i.match(column)
+            warn "[groupdate] Non-attribute argument: #{column}. Use Arel.sql() for known-safe values. This will raise an error in Groupdate 6"
+          end
+        end
+        column
+      end
+
+      # resolves eagerly
+      # need to convert both where_clause (easy)
+      # and group_clause (not easy) if want to avoid this
+      def resolve_column(relation, column)
+        node = relation.send(:relation).send(:arel_columns, [column]).first
+        node = Arel::Nodes::SqlLiteral.new(node) if node.is_a?(String)
+        relation.connection.visitor.accept(node, Arel::Collectors::SQLString.new).value
+      end
+    end
+  end
+end

data/lib/groupdate/adapters/mysql_adapter.rb

@@ -0,0 +1,56 @@
+module Groupdate
+  module Adapters
+    class MySQLAdapter < BaseAdapter
+      def group_clause
+        time_zone = @time_zone.tzinfo.name
+        day_start_column = "CONVERT_TZ(#{column}, '+00:00', ?) - INTERVAL ? second"
+
+        query =
+          case period
+          when :minute_of_hour
+            ["MINUTE(#{day_start_column})", time_zone, day_start]
+          when :hour_of_day
+            ["HOUR(#{day_start_column})", time_zone, day_start]
+          when :day_of_week
+            ["DAYOFWEEK(#{day_start_column}) - 1", time_zone, day_start]
+          when :day_of_month
+            ["DAYOFMONTH(#{day_start_column})", time_zone, day_start]
+          when :day_of_year
+            ["DAYOFYEAR(#{day_start_column})", time_zone, day_start]
+          when :month_of_year
+            ["MONTH(#{day_start_column})", time_zone, day_start]
+          when :week
+            ["CONVERT_TZ(DATE_FORMAT(#{day_start_column} - INTERVAL ((? + DAYOFWEEK(#{day_start_column})) % 7) DAY, '%Y-%m-%d 00:00:00') + INTERVAL ? second, ?, '+00:00')", time_zone, day_start, 12 - week_start, time_zone, day_start, day_start, time_zone]
+          when :quarter
+            ["CONVERT_TZ(DATE_FORMAT(DATE(CONCAT(YEAR(#{day_start_column}), '-', LPAD(1 + 3 * (QUARTER(#{day_start_column}) - 1), 2, '00'), '-01')), '%Y-%m-%d %H:%i:%S') + INTERVAL ? second, ?, '+00:00')", time_zone, day_start, time_zone, day_start, day_start, time_zone]
+          when :custom
+            ["FROM_UNIXTIME((UNIX_TIMESTAMP(#{column}) DIV ?) * ?)", n_seconds, n_seconds]
+          else
+            format =
+              case period
+              when :second
+                "%Y-%m-%d %H:%i:%S"
+              when :minute
+                "%Y-%m-%d %H:%i:00"
+              when :hour
+                "%Y-%m-%d %H:00:00"
+              when :day
+                "%Y-%m-%d 00:00:00"
+              when :month
+                "%Y-%m-01 00:00:00"
+              else # year
+                "%Y-01-01 00:00:00"
+              end
+
+            ["CONVERT_TZ(DATE_FORMAT(#{day_start_column}, ?) + INTERVAL ? second, ?, '+00:00')", time_zone, day_start, format, day_start, time_zone]
+          end
+
+        clean_group_clause(@relation.send(:sanitize_sql_array, query))
+      end
+
+      def clean_group_clause(clause)
+        clause.gsub(/ (\-|\+) INTERVAL 0 second/, "")
+      end
+    end
+  end
+end

data/lib/groupdate/adapters/postgresql_adapter.rb

@@ -0,0 +1,44 @@
+module Groupdate
+  module Adapters
+    class PostgreSQLAdapter < BaseAdapter
+      def group_clause
+        time_zone = @time_zone.tzinfo.name
+        day_start_column = "#{column}::timestamptz AT TIME ZONE ? - INTERVAL ?"
+        day_start_interval = "#{day_start} second"
+
+        query =
+          case period
+          when :minute_of_hour
+            ["EXTRACT(MINUTE FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :hour_of_day
+            ["EXTRACT(HOUR FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_week
+            ["EXTRACT(DOW FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_month
+            ["EXTRACT(DAY FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_year
+            ["EXTRACT(DOY FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :month_of_year
+            ["EXTRACT(MONTH FROM #{day_start_column})::integer", time_zone, day_start_interval]
+          when :week
+            ["(DATE_TRUNC('day', #{day_start_column} - INTERVAL '1 day' * ((? + EXTRACT(DOW FROM #{day_start_column})::integer) % 7)) + INTERVAL ?) AT TIME ZONE ?", time_zone, day_start_interval, 13 - week_start, time_zone, day_start_interval, day_start_interval, time_zone]
+          when :custom
+            ["TO_TIMESTAMP(FLOOR(EXTRACT(EPOCH FROM #{column}::timestamptz) / ?) * ?)", n_seconds, n_seconds]
+          else
+            if day_start == 0
+              # prettier
+              ["DATE_TRUNC(?, #{day_start_column}) AT TIME ZONE ?", period, time_zone, day_start_interval, time_zone]
+            else
+              ["(DATE_TRUNC(?, #{day_start_column}) + INTERVAL ?) AT TIME ZONE ?", period, time_zone, day_start_interval, day_start_interval, time_zone]
+            end
+          end
+
+        clean_group_clause(@relation.send(:sanitize_sql_array, query))
+      end
+
+      def clean_group_clause(clause)
+        clause.gsub(/ (\-|\+) INTERVAL '0 second'/, "")
+      end
+    end
+  end
+end

data/lib/groupdate/adapters/redshift_adapter.rb

@@ -0,0 +1,39 @@
+module Groupdate
+  module Adapters
+    class RedshiftAdapter < BaseAdapter
+      def group_clause
+        time_zone = @time_zone.tzinfo.name
+        day_start_column = "CONVERT_TIMEZONE(?, #{column}::timestamp) - INTERVAL ?"
+        day_start_interval = "#{day_start} second"
+
+        query =
+          case period
+          when :minute_of_hour
+            ["EXTRACT(MINUTE from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :hour_of_day
+            ["EXTRACT(HOUR from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_week
+            ["EXTRACT(DOW from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_month
+            ["EXTRACT(DAY from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :day_of_year
+            ["EXTRACT(DOY from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :month_of_year
+            ["EXTRACT(MONTH from #{day_start_column})::integer", time_zone, day_start_interval]
+          when :week # start on Sunday, not Redshift default Monday
+            # Redshift does not return timezone information; it
+            # always says it is in UTC time, so we must convert
+            # back to UTC to play properly with the rest of Groupdate.
+            week_start_interval = "#{week_start} day"
+            ["CONVERT_TIMEZONE(?, 'Etc/UTC', DATE_TRUNC('week', #{day_start_column} - INTERVAL ?) + INTERVAL ? + INTERVAL ?)::timestamp", time_zone, time_zone, day_start_interval, week_start_interval, week_start_interval, day_start_interval]
+          when :custom
+            raise Groupdate::Error, "Not implemented yet"
+          else
+            ["CONVERT_TIMEZONE(?, 'Etc/UTC', DATE_TRUNC(?, #{day_start_column}) + INTERVAL ?)::timestamp", time_zone, period, time_zone, day_start_interval, day_start_interval]
+          end
+
+        @relation.send(:sanitize_sql_array, query)
+      end
+    end
+  end
+end