groupdate2 4.1.5 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a798d7e082e32adf30f0fd07348f8fec6369006
-  data.tar.gz: 6fc8861fc493d524bc29b8be51ef030887d38dd4
+  metadata.gz: 7dfbcb0e43b31bb8e60084798e7b36b30fe7fb90
+  data.tar.gz: 0ac168fda29a6df9f1e28272ef80ee11c0029459
 SHA512:
-  metadata.gz: 3c3459a9aa602d466dac261078dcd3dda23481e57b9cf1cf644699353f18e03af3924d0fda5f45887a6fad83d715ea7a0fc07f5772b30b0d4c34159fa0092bd3
-  data.tar.gz: fe47222def4bec06307c1930aff1c81b2bc6dd2819e9413d4df7e766345834d80271fa899e06a3f6655b53337e3864c68a32b2351f99432760f46731ec7b6c7d
+  metadata.gz: b272dfa52234edaad18d44b78b129106b53a44ed79e577f593684428ba7b80972d78a48d99715ba52e0ecafab1e716b8cd318fd657293066ee91ad5f26f5c1cd
+  data.tar.gz: 53d31a3bd69f26d2cdb32617e8741c25a66991b29d1bca1544ec494991007b0ea5ed6b54040d0df49a32372958c647dd81975f54591c4da5856ee49bc7dd8456

data/CHANGELOG.md

@@ -1,31 +1,55 @@
-## 4.1.2
+## 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
+- Fixed deprecation warnings in Ruby 2.7
+- Deprecated positional arguments for time zone and range
+
+## 4.2.0 (2019-10-28)
+
+- Added `day_of_year`
+- Dropped support for Rails 4.2
+
+## 4.1.2 (2019-05-26)
 
 - Fixed error with empty data and `current: false`
 - Fixed error in time zone check for Rails < 5.2
 - Prevent infinite loop with endless ranges
 
-## 4.1.1
+## 4.1.1 (2018-12-11)
 
 - Made column resolution consistent with `group`
 - Added support for `alias_attribute`
 
-## 4.1.0
+## 4.1.0 (2018-11-04)
 
 - Many performance improvements
 - Added check for consistent time zone info
 - Fixed error message for invalid queries with MySQL and SQLite
 - Fixed issue with enumerable methods ignoring nils
 
-## 4.0.2
+## 4.0.2 (2018-10-15)
 
 - Make `current` option work without `last`
 - Fixed default value for `maximum`, `minimum`, and `average` (periods with no results now return `nil` instead of `0`, pass `default_value: 0` for previous behavior)
 
-## 4.0.1
+## 4.0.1 (2018-05-03)
 
 - Fixed incorrect range with `last` option near time change
 
-## 4.0.0
+## 4.0.0 (2018-02-21)
 
 - Custom calculation methods are supported by default - `groupdate_calculation_methods` is no longer needed
 
@@ -37,37 +61,37 @@ Breaking changes
 - `week_start` now affects `day_of_week`
 - Removed support for `reverse_order` (was never supported in Rails 5)
 
-## 3.2.1
+## 3.2.1 (2018-02-21)
 
 - Added `minute_of_hour`
 - Added support for `unscoped`
 
-## 3.2.0
+## 3.2.0 (2017-01-30)
 
 - Added limited support for SQLite
 
-## 3.1.1
+## 3.1.1 (2016-10-25)
 
 - Fixed `current: false`
 - Fixed `last` with `group_by_quarter`
 - Raise `ArgumentError` when `last` option is not supported
 
-## 3.1.0
+## 3.1.0 (2016-10-22)
 
 - Better support for date columns with `time_zone: false`
 - Better date range handling for `range` option
 
-## 3.0.2
+## 3.0.2 (2016-08-09)
 
 - Fixed `group_by_period` with associations
 - Fixed `week_start` option for enumerables
 
-## 3.0.1
+## 3.0.1 (2016-07-13)
 
 - Added support for Redshift
 - Fix for infinite loop in certain cases for Rails 5
 
-## 3.0.0
+## 3.0.0 (2016-05-30)
 
 Breaking changes
 
@@ -75,16 +99,16 @@ Breaking changes
 - 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 types and order, and plays nicely with other options.
 
-## 2.5.3
+## 2.5.3 (2016-04-28)
 
 - All tests green with `mysql` gem
 - Added support for decimal day start
 
-## 2.5.2
+## 2.5.2 (2016-02-16)
 
 - Added `dates` option to return dates for day, week, month, quarter, and year
 
-## 2.5.1
+## 2.5.1 (2016-02-03)
 
 - Added `group_by_quarter`
 - Added `default_value` option
@@ -92,13 +116,13 @@ Breaking changes
 - Raise `ArgumentError` if no field specified
 - Added support for ActiveRecord 5 beta
 
-## 2.5.0
+## 2.5.0 (2015-09-29)
 
 - Added `group_by_period` method
 - Added `current` option
 - Raise `ArgumentError` if no block given to enumerable
 
-## 2.4.0
+## 2.4.0 (2014-12-28)
 
 - Added localization
 - Added `carry_forward` option
@@ -106,77 +130,77 @@ Breaking changes
 - Fixed issue w/ Brasilia Summer Time
 - Fixed issues w/ ActiveRecord 4.2
 
-## 2.3.0
+## 2.3.0 (2014-08-31)
 
 - Raise error when ActiveRecord::Base.default_timezone is not `:utc`
 - Added `day_of_month`
 - Added `month_of_year`
 - Do not quote column name
 
-## 2.2.1
+## 2.2.1 (2014-06-23)
 
 - Fixed ActiveRecord 3 associations
 
-## 2.2.0
+## 2.2.0 (2014-06-22)
 
 - Added support for arrays and hashes
 
-## 2.1.1
+## 2.1.1 (2014-05-17)
 
 - Fixed format option with multiple groups
 - Better error message if time zone support is missing for MySQL
 
-## 2.1.0
+## 2.1.0 (2014-03-16)
 
 - Added last option
 - Added format option
 
-## 2.0.4
+## 2.0.4 (2014-03-12)
 
 - Added multiple groups
 - Added order
 - Subsequent methods no longer modify relation
 
-## 2.0.3
+## 2.0.3 (2014-03-11)
 
 - Implemented respond_to?
 
-## 2.0.2
+## 2.0.2 (2014-03-11)
 
 - where, joins, and includes no longer need to be before the group_by method
 
-## 2.0.1
+## 2.0.1 (2014-03-07)
 
 - Use time zone instead of UTC for results
 
-## 2.0.0
+## 2.0.0 (2014-03-07)
 
 - Returns entire series by default
 - Added day_start option
 - Better interface
 
-## 1.0.5
+## 1.0.5 (2014-03-06)
 
 - Added global time_zone option
 
-## 1.0.4
+## 1.0.4 (2013-07-20)
 
 - Added global week_start option
 - Fixed bug with NULL values and series
 
-## 1.0.3
+## 1.0.3 (2013-07-05)
 
 - Fixed deprecation warning when used with will_paginate
 - Fixed bug with DateTime series
 
-## 1.0.2
+## 1.0.2 (2013-06-10)
 
 - Added :start option for custom week start for group_by_week
 
-## 1.0.1
+## 1.0.1 (2013-06-03)
 
 - Fixed series for Rails < 3.2 and MySQL
 
-## 1.0.0
+## 1.0.0 (2013-05-15)
 
 - First major release

data/CONTRIBUTING.md

@@ -57,7 +57,7 @@ brew services start mysql
 
 # create databases
 createdb groupdate_test
-mysql -u root -e "create database groupdate_test"
+mysqladmin create groupdate_test
 mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
 
 # clone the repo and run the tests

data/LICENSE.txt

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

data/README.md

@@ -1,16 +1,50 @@
 # Groupdate2
-groupdate2 is an enhanced version of the beautiful [Groupdate](https://github.com/ankane/groupdate) gem.
-It adds MS SQL Server (2016 and above) support by using `(AT TIME ZONE)`.
+groupdate2 is an enhanced version of the beautiful [Groupdate](https://github.com/ankane/groupdate) gem, it adds more features to Groupdate
+- SQL Server 2016+ support
+- series_label support
 
-In JRuby, it relies on `activerecord-sqlserver-adapter` `jdbc-mode` branch, which is not ideal. The plan is using `activerecord-jdbcsqlserver-adapter` when JRuby 9.2+ is supported.
-
-# Version
-## 4.1.x
-This version corresponds to groupdate 4.1.2 with SQL Server support.
-
-## Installation
+# Installation
 Add this line to your application’s Gemfile:
 ```ruby
 gem 'groupdate2'
 ```
 
+# Features
+## SQL Server 2016+
+MS SQL Server (2016 and above) support by using (AT TIME ZONE).
+
+## series_label, an option to include `group clause` in selected result
+### User case
+If you use groupdate not with ActiveRecord::Calculations, but manually selecting the calculation like:
+```sql
+sql = "COUNT(*) AS count, AVG(delivery.volume/truck.capacity) AS percentage, MIN(collected_at) AS collected_at"
+```
+Delivery.select(sql).group_by_day(:collected_at).to_a
+
+It works well except the series label is not included in the result. I have to use MIN(collected_at) to have it, then convert it to the correct label in ruby code. It works but is cumbersome.
+
+With this new option `series_label: collected_at_date`, it indicates the group clause should be included in the result and can be accessed by the method collected_at_date.
+
+### Notes
+- !!! This option does NOT work with ActiveRecord::Calculations.
+- The series_label respects other Groupdate options like :locale, :dates and :format
+
+[See more options](https://github.com/ankane/groupdate)
+
+### An example
+```ruby
+users = User.select('COUNT(*) AS total, AVG(age) as average_age').group_by_month(:created_at, series_label: :created_at_month)
+
+#The returned result would have attributes:
+users.first.created_at_month
+users.first.total
+users.first.average_age
+```
+
+# Upgrading
+## 5.0.x
+- SQL server support
+- series_label support
+
+## 4.1.x
+This version corresponds to groupdate 4.1.2 with SQL Server support.

data/lib/groupdate/active_record.rb

@@ -4,3 +4,4 @@ require "groupdate/relation"
 
 ActiveRecord::Base.extend(Groupdate::QueryMethods)
 ActiveRecord::Relation.include(Groupdate::Relation)
+ActiveRecord::Relation.prepend(Groupdate::RelationRecords)

data/lib/groupdate/enumerable.rb

@@ -1,31 +1,25 @@
 module Enumerable
   Groupdate::PERIODS.each do |period|
-    define_method :"group_by_#{period}" do |*args, &block|
+    define_method :"group_by_#{period}" do |*args, **options, &block|
       if block
-        Groupdate::Magic::Enumerable.group_by(self, period, args[0] || {}, &block)
+        raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0)" if args.any?
+        Groupdate::Magic::Enumerable.group_by(self, period, options, &block)
       elsif respond_to?(:scoping)
-        scoping { @klass.send(:"group_by_#{period}", *args, &block) }
+        scoping { @klass.group_by_period(period, *args, **options, &block) }
       else
         raise ArgumentError, "no block given"
       end
     end
   end
 
-  def group_by_period(*args, &block)
+  def group_by_period(period, *args, **options, &block)
     if block || !respond_to?(:scoping)
-      period = args[0]
-      options = args[1] || {}
+      raise ArgumentError, "wrong number of arguments (given #{args.size + 1}, expected 1)" if args.any?
 
-      options = options.dup
-      # to_sym is unsafe on user input, so convert to strings
-      permitted_periods = ((options.delete(:permit) || Groupdate::PERIODS).map(&:to_sym) & Groupdate::PERIODS).map(&:to_s)
-      if permitted_periods.include?(period.to_s)
-        send("group_by_#{period}", options, &block)
-      else
-        raise ArgumentError, "Unpermitted period"
-      end
+      Groupdate::Magic.validate_period(period, options.delete(:permit))
+      send("group_by_#{period}", **options, &block)
     else
-      scoping { @klass.send(:group_by_period, *args, &block) }
+      scoping { @klass.group_by_period(period, *args, **options, &block) }
     end
   end
 end

data/lib/groupdate/magic.rb

@@ -2,18 +2,42 @@ require "i18n"
 
 module Groupdate
   class Magic
+    DAYS = [:monday, :tuesday, :wednesday, :thursday, :friday, :saturday, :sunday]
+
     attr_accessor :period, :options, :group_index
 
     def initialize(period:, **options)
       @period = period
       @options = options
 
-      unknown_keywords = options.keys - [:day_start, :time_zone, :dates, :series, :week_start, :format, :locale, :range, :reverse]
+      validate_keywords
+      validate_arguments
+    end
+
+    def validate_keywords
+      known_keywords = [:time_zone, :dates, :series, :format, :locale, :range, :reverse, :series_label]
+
+      if %i[week day_of_week].include?(period)
+        known_keywords << :week_start
+      end
+
+      if %i[day week month quarter year day_of_week hour_of_day day_of_month day_of_year month_of_year].include?(period)
+        known_keywords << :day_start
+      else
+        # prevent Groupdate.day_start from applying
+        @day_start = 0
+      end
+
+      unknown_keywords = options.keys - known_keywords
       raise ArgumentError, "unknown keywords: #{unknown_keywords.join(", ")}" if unknown_keywords.any?
+    end
 
-      raise Groupdate::Error, "Unrecognized time zone" unless time_zone
-      raise Groupdate::Error, "Unrecognized :week_start option" if period == :week && !week_start
-      raise Groupdate::Error, "Cannot use endless range for :range option" if options[:range].is_a?(Range) && !options[:range].end
+    def validate_arguments
+      # TODO better messages
+      raise ArgumentError, "Unrecognized time zone" unless time_zone
+      raise ArgumentError, "Unrecognized :week_start option" unless week_start
+      raise ArgumentError, "Cannot use endless range for :range option" if options[:range].is_a?(Range) && !options[:range].end
+      raise ArgumentError, ":day_start must be between 0 and 24" if (day_start / 3600) < 0 || (day_start / 3600) >= 24
     end
 
     def time_zone
@@ -25,13 +49,20 @@ module Groupdate
     end
 
     def week_start
-      @week_start ||= [:mon, :tue, :wed, :thu, :fri, :sat, :sun].index((options[:week_start] || options[:start] || Groupdate.week_start).to_sym)
+      @week_start ||= begin
+        v = (options[:week_start] || Groupdate.week_start).to_sym
+        DAYS.index(v) || [:mon, :tue, :wed, :thu, :fri, :sat, :sun].index(v)
+      end
     end
 
     def day_start
       @day_start ||= ((options[:day_start] || Groupdate.day_start).to_f * 3600).round
     end
 
+    def series_label
+      @series_label ||= (options[:series_label].present? ? options[:series_label] : nil)
+    end
+
     def series_builder
       @series_builder ||=
         SeriesBuilder.new(
@@ -47,6 +78,11 @@ module Groupdate
       series_builder.time_range
     end
 
+    def self.validate_period(period, permit)
+      permitted_periods = ((permit || Groupdate::PERIODS).map(&:to_sym) & Groupdate::PERIODS).map(&:to_s)
+      raise ArgumentError, "Unpermitted period" unless permitted_periods.include?(period.to_s)
+    end
+
     class Enumerable < Magic
       def group_by(enum, &_block)
         group = enum.group_by do |v|
@@ -85,10 +121,10 @@ module Groupdate
       def cast_method
         @cast_method ||= begin
           case period
+          when :minute_of_hour, :hour_of_day, :day_of_month, :day_of_year, :month_of_year
+            lambda { |k| k.to_i }
           when :day_of_week
             lambda { |k| (k.to_i - 1 - week_start) % 7 }
-          when :hour_of_day, :day_of_month, :month_of_year, :minute_of_hour
-            lambda { |k| k.to_i }
           else
             utc = ActiveSupport::TimeZone["UTC"]
             lambda { |k| (k.is_a?(String) || !k.respond_to?(:to_time) ? utc.parse(k.to_s) : k.to_time).in_time_zone(time_zone) }
@@ -130,6 +166,20 @@ module Groupdate
         end
       end
 
+      def perform_series_label(relation, result)
+        label = options[:series_label]
+        return result unless label.present?
+
+        result.map do |r|
+          r.send("#{label}=", cast_series_label(r.send(label)))
+          r
+        end
+      end
+
+      def cast_series_label(original_label)
+        series_builder.format_series_label(cast_method.call(original_label))
+      end
+
       def self.generate_relation(relation, field:, **options)
         magic = Groupdate::Magic::Relation.new(**options)
 
@@ -142,7 +192,8 @@ module Groupdate
             time_zone: magic.time_zone,
             time_range: magic.time_range,
             week_start: magic.week_start,
-            day_start: magic.day_start
+            day_start: magic.day_start,
+            series_label: magic.series_label
           ).generate
 
         # add Groupdate info
@@ -159,6 +210,13 @@ module Groupdate
         end
         result
       end
+
+      def self.process_series_label(relation, result)
+        relation.groupdate_values.reverse.each do |gv|
+          result = gv.perform_series_label(relation, result)
+        end
+        result
+      end
     end
   end
 end