merch_calendar 0.1.0.rc2 → 0.1.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4258c9ca91b7427a13a40d020ea448f7a0bce7d3
-  data.tar.gz: e5892f68ea348e3901339aebdd186200773333bc
+  metadata.gz: 529c719788c4f0aada0e215af345aa00ec9d055f
+  data.tar.gz: 79f5749368eff3b9607649efac54ec8a54cacbd8
 SHA512:
-  metadata.gz: 50c31a68c19cc6edd3aecf26467788afd0c23d1f688c97d2d08ee1a06ebe2c2ea6cd67445f891a8b6f22371a509a7cb4779023f6d48e6022e54b2c4d1f5e9462
-  data.tar.gz: d5a02533ff081b5d4fe07b3ad80fd882a62834c19a79023351c3c079664b9b169fd5e7cfb2a8c5026aceb81e25e63637280dd0ed13402212df80530e47283e08
+  metadata.gz: 1cbcf6b7df354163f93069a82f9f05a60882cd129be90335777c30b39dd735065fa851dce568c13a986d660654a8e610df81cc1ced035340b7e473f63f1fea41
+  data.tar.gz: f363bb9980350ccc5867679301afb2380d67b99a6bd60cf3472122e922ca62b6c07e5ff1a9733223d1ee5f5a60f3d6e191f601ac28c44d4956c3634f0be5853a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    merch_calendar (0.1.0.rc2)
+    merch_calendar (0.1.0.rc3)
 
 GEM
   remote: https://www.rubygems.org/

data/README.md

@@ -49,82 +49,85 @@ puts merch_week.to_s(:long) # "2013:48 Dec W5"
 puts merch_week.to_s(:elasticsearch) # "2013-12w05"
 ```
 
-This can also be used on the `MerchCalendar` module. All `start_` and `end_` methods can be called, along with a few additional ones.
 
-```ruby
-# All examples below return a Date object for the start of May within the 2014 merch year
-MerchCalendar.start_of_month(2014, 5)
-MerchCalendar.start_of_month(2014, month: 5)
-MerchCalendar.start_of_month(2014, julian_month: 5)
-
-# This is the same as May, because "Merch" months are shifted by 1.
-# i.e. month 1 is actually February
-# You probably will never use this, but it is available.
-MerchCalendar.start_of_month(2014, merch_month: 4)
-```
+### Merch retail calendar
 
-#### Confusing things to look out for:
-
-Merch calendars have the first month in February, and the last (12th) month is in January of the following year. In the code block above, each method is *asking* a very different question. This will definitely cause confusion, so here are some explanations.
+Merch calendars have their first month in February, and the last (12th) month is in January of the
+following year.
 
 ```ruby
-# This is asking "In the Merch year of 2014, where is the month of January?"
-# January is the last (12th) month of a merch year, so this date will be in the NEXT
-# julian calendar year
-MerchCalendar.start_of_month(2014, 1)
-MerchCalendar.start_of_month(2014, month: 1)
-MerchCalendar.start_of_month(2014, julian_month: 1)
-# => 2015-01-04
-#    ^^^^ - NEXT year
+# This is asking "In the Merch year of 2014, what is the Gregorian calendar date of
+# the start of the first month?"
+retail_calendar = MerchCalendar::RetailCalendar.new
 
-# This is asking "When is the start of the FIRST month of the merch year 2014"
-MerchCalendar.start_of_month(2014, merch_month: 1)
+retail_calendar.start_of_month(2014, 1)
 # => 2014-02-02
 
+retail_calendar.start_of_month(2014, 12)
+# => 2015-01-04
 ```
 
 This table should describe the progression of dates:
 
-| N  | `start_of_month(2014, N)` | `start_of_month(2014, merch_month: N)` |
-| ------------- | ------------- | ------------- |
-| 1  | **2015-01-04**  | 2014-02-02 |
-| 2  | 2014-02-02  | 2014-03-02 |
-| 3  | 2014-03-02  | 2014-04-06 |
-| 4  | 2014-04-06  | 2014-05-04 |
-| 5  | 2014-05-04  | 2014-06-01 |
-| 6  | 2014-06-01  | 2014-07-06 |
-| 7  | 2014-07-06  | 2014-08-03 |
-| 8  | 2014-08-03  | 2014-08-31 |
-| 9  | 2014-08-31  | 2014-10-05 |
-| 10  | 2014-10-05  | 2014-11-02 |
-| 11  | 2014-11-02  | 2014-11-30 |
-| 12  | 2014-11-30  | **2015-01-04** |
+| N   |  `start_of_month(2014, N)` |
+| ------------- | ------------- |
+| 1   | 2014-02-02 |
+| 2   | 2014-03-02 |
+| 3   | 2014-04-06 |
+| 4   | 2014-05-04 |
+| 5   | 2014-06-01 |
+| 6   | 2014-07-06 |
+| 7   | 2014-08-03 |
+| 8   | 2014-08-31 |
+| 9   | 2014-10-05 |
+| 10  | 2014-11-02 |
+| 11  | 2014-11-30 |
+| 12  | 2015-01-04 |
 
 
 Other useful methods:
 
 ```ruby
 # 52 or 53 (depending on leap year)
-MerchCalendar.weeks_in_year(2015)
+retail_calendar.weeks_in_year(2016)
+# => 52
+retail_calendar.weeks_in_year(2017)
+# => 53
+
+# get the start date of a given merch week
+retail_calendar.start_of_week(2017, 4, 1)
+# => #<Date: 2017-04-30 ((2457874j,0s,0n),+0s,2299161j)>
+
+# get the end date of a given merch week
+retail_calendar.end_of_week(2017, 4, 1)
+#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
+```
+
+### Offset fiscal year calendars
+Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that is offset of
+the traditional retail calendar.  The `MerchCalendar::FiscalYearCalendar` class allows you to easily
+offset the start of year to match your fiscal calendar.
+
+```ruby
+fiscal_calendar = MerchCalendar::FiscalYearCalendar.new
 
-# returns an array of MerchWeek objects for each week within the provided month
-MerchCalendar.weeks_for_month(2014, 1)
+# 52 or 53 (depending on leap year)
+fiscal_calendar.weeks_in_year(2017)
+# => 52
+fiscal_calendar.weeks_in_year(2018)
+# => 53
 
 # get the start date of a given merch week
-MerchCalendar.start_of_week(2017, 4, 1)
-# => #<Date: 2017-04-02 ((2457846j,0s,0n),+0s,2299161j)>
+fiscal_calendar.start_of_week(2017, 1, 1)
+# => #<Date: 2016-07-31 ((2457601j,0s,0n),+0s,2299161j)>
 
 # get the end date of a given merch week
-MerchCalendar.end_of_week(2017, 4, 1)
-# => #<Date: 2017-04-08 ((2457852j,0s,0n),+0s,2299161j)>
+fiscal_calendar.end_of_week(2017, 4, 1)
+#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
 ```
 
 ## Documentation
 You can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).
 
-
-## Roadmap
-* Support for 4-4-5 calendars
-
 ## License
 MerchCalendar is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/merch_calendar/fiscal_year_calendar.rb

@@ -2,17 +2,38 @@ require "merch_calendar/retail_calendar"
 
 module MerchCalendar
   class FiscalYearCalendar
-    def initialize
+    # Stitch Fix's fiscal year starts two quarters *before* (hence the negative number) the start of the 
+    # merch/retail calendar year.
+    STITCH_FIX_FY_QUARTER_OFFSET = -2
+
+    QUARTER_1 = 1
+    QUARTER_4 = 4
+
+    # @param fy_quarter_offset [Fixnum]
+    #   The number of quarters before or after the start of the traditional NRF retail calendar that the year
+    #   should begin.
+    #     ex) Stitch Fix's fiscal year calendar starts in August of the prior gregorian calendar year.
+    #         February 2017 = Traditional retail month 1, year 2017 
+    #         August 2016 = Offset retail month 1, year 2017 (2 quarters earlier)
+    def initialize(fy_quarter_offset = STITCH_FIX_FY_QUARTER_OFFSET)
+      @fy_quarter_offset = fy_quarter_offset
+
+      # TODO: support other fiscal year offsets
+      if fy_quarter_offset != STITCH_FIX_FY_QUARTER_OFFSET
+        raise NotImplementedError.new("FY quarter offset of #{fy_quarter_offset} not yet supported")
+      end
+
       @retail_calendar = RetailCalendar.new
     end
 
-    # The day after last years' end date
+    # The date of the first day of the year
     def start_of_year(year)
-      start_of_quarter(year, 1)
+      start_of_quarter(year, QUARTER_1)
     end
 
+    # The date of the last day of the year
     def end_of_year(year)
-      end_of_quarter(year, 4)
+      end_of_quarter(year, QUARTER_4)
     end
 
     # Return the starting date for a particular quarter
@@ -25,10 +46,18 @@ module MerchCalendar
       @retail_calendar.end_of_quarter(*offset_quarter(year, quarter))
     end
 
+    # The date of the first day of the merch month
+    # @param [Fixnum] year - the fiscal year
+    # @param [Fixnum] merch_month - the nth month of the offset calendar
+    #   ex) for an offset of +/- 2 quarters, month 1 = August
     def start_of_month(year, merch_month)
       @retail_calendar.start_of_month(*offset_month(year, merch_month))
     end
 
+    # The date of the last day of the merch month
+    # @param [Fixnum] year - the fiscal year
+    # @param [Fixnum] merch_month - the nth month of the offset calendar
+    #   ex) for an offset of +/- 2 quarters, month 1 = August
     def end_of_month(year, merch_month)
       @retail_calendar.end_of_month(*offset_month(year, merch_month))
     end
@@ -43,20 +72,47 @@ module MerchCalendar
       @retail_calendar.end_of_week(*offset_month(year, merch_month), merch_week)
     end
 
+    # Returns the number of weeks in the fiscal year
     def weeks_in_year(year)
-      @retail_calendar.weeks_in_year(year - 1)
+      @retail_calendar.weeks_in_year(offset_year(year))
     end
 
     private
 
+    # Offsets the quarter based on the fiscal year quarter offset
+    # returns: ofset [year, quarter]
     def offset_quarter(year, quarter)
       # first quarter in fiscal calendar is Q3 of retail calendar of previous year
-      yr, qt = quarter >= 3 ? [year, quarter - 2] : [year - 1, quarter + 2]
+      if quarter >= 1 + @fy_quarter_offset.abs 
+        [year, quarter + @fy_quarter_offset]
+      else
+        [year - 1, quarter - @fy_quarter_offset]
+      end
     end
 
+    # Offsets the month based on the fiscal year quarter offset
+    # returns: ofset [year, month]
     def offset_month(year, month)
-      # first month in fiscal calendar is the sixth month in the retail calendar
-      yr, mn = month >= 7 ? [year, month - 6] : [year - 1, month + 6]
+      # 3 - number of months in a quarter
+      month_offset = @fy_quarter_offset * 3
+
+      if month >= (month_offset.abs + 1) 
+        [year, month + month_offset] 
+      else
+        [year - 1, month - month_offset]
+      end
+    end
+
+    # Offsets the year based on the fiscal year quarter offset
+    # returns: ofset year
+    def offset_year(year)
+      if @fy_quarter_offset < 0
+        year -= 1
+      elsif @fy_quarter_offset > 0
+        year += 1
+      else
+        year
+      end
     end
   end
 end

data/lib/merch_calendar/retail_calendar.rb

@@ -2,6 +2,11 @@ require "date"
 
 module MerchCalendar
   class RetailCalendar
+    QUARTER_1 = 1
+    QUARTER_2 = 2
+    QUARTER_3 = 3
+    QUARTER_4 = 4
+
     def end_of_year(year)
       year_end = Date.new((year + 1), 1, -1)
       wday = (year_end.wday + 1) % 7
@@ -61,13 +66,13 @@ module MerchCalendar
     # Return the starting date for a particular quarter
     def start_of_quarter(year, quarter)
       case quarter
-      when 1
+      when QUARTER_1
         start_of_month(year, 1)
-      when 2
+      when QUARTER_2
         start_of_month(year, 4)
-      when 3
+      when QUARTER_3
         start_of_month(year, 7)
-      when 4
+      when QUARTER_4
         start_of_month(year, 10)
       end
     end
@@ -75,13 +80,13 @@ module MerchCalendar
     # Return the ending date for a particular quarter
     def end_of_quarter(year, quarter)
       case quarter
-      when 1
+      when QUARTER_1
         end_of_month(year, 3)
-      when 2
+      when QUARTER_2
         end_of_month(year, 6)
-      when 3
+      when QUARTER_3
         end_of_month(year, 9)
-      when 4
+      when QUARTER_4
         end_of_month(year, 12)
       end
     end

data/lib/merch_calendar/version.rb

@@ -1,3 +1,3 @@
 module MerchCalendar
-  VERSION = '0.1.0.rc2'
+  VERSION = '0.1.0.rc3'
 end

data/spec/merch_calendar/fiscal_year_calendar_spec.rb

@@ -1,133 +1,145 @@
 require "spec_helper"
 
 RSpec.describe MerchCalendar::FiscalYearCalendar do
-  describe "#weeks_in_year" do
-    it "returns 53 for a leap year - 2013" do
-      expect(subject.weeks_in_year(2013)).to eq 53
-    end
+  context "the default fy_offset - 2 quarters earlier" do
+    describe "#weeks_in_year" do
+      it "returns 53 for a leap year - 2013" do
+        expect(subject.weeks_in_year(2013)).to eq 53
+      end
 
-    it "returns 52 for a normal year" do
-      expect(subject.weeks_in_year(2014)).to eq 52
-    end
+      it "returns 52 for a normal year" do
+        expect(subject.weeks_in_year(2014)).to eq 52
+      end
 
-    it "returns 52 for a normal year" do
-      expect(subject.weeks_in_year(2015)).to eq 52
-    end
+      it "returns 52 for a normal year" do
+        expect(subject.weeks_in_year(2015)).to eq 52
+      end
 
-    it "returns 52 for a normal year" do
-      expect(subject.weeks_in_year(2016)).to eq 52
-    end
+      it "returns 52 for a normal year" do
+        expect(subject.weeks_in_year(2016)).to eq 52
+      end
 
-    it "returns 52 for a normal year" do
-      expect(subject.weeks_in_year(2017)).to eq 52
-    end
+      it "returns 52 for a normal year" do
+        expect(subject.weeks_in_year(2017)).to eq 52
+      end
 
-    it "returns 53 for a leap year - 2018" do
-      expect(subject.weeks_in_year(2018)).to eq 53
-    end
+      it "returns 53 for a leap year - 2018" do
+        expect(subject.weeks_in_year(2018)).to eq 53
+      end
 
-    it "returns 52 for a normal year" do
-      expect(subject.weeks_in_year(2019)).to eq 52
+      it "returns 52 for a normal year" do
+        expect(subject.weeks_in_year(2019)).to eq 52
+      end
     end
-  end
 
-  describe "#start_of_week" do
-    it "returns the correct date for 2017-1-1 (2017-Aug-wk1)" do
-      expect(subject.start_of_week(2017, 1, 1)).to eq Date.new(2016, 7, 31)
-    end
+    describe "#start_of_week" do
+      it "returns the correct date for 2017-1-1 (2017-Aug-wk1)" do
+        expect(subject.start_of_week(2017, 1, 1)).to eq Date.new(2016, 7, 31)
+      end
 
-    it "returns the correct Date for 2018-1-1 (2018-Aug-wk1)" do
-      expect(subject.start_of_week(2018, 1, 1)).to eq Date.new(2017, 7, 30)
-    end
+      it "returns the correct Date for 2018-1-1 (2018-Aug-wk1)" do
+        expect(subject.start_of_week(2018, 1, 1)).to eq Date.new(2017, 7, 30)
+      end
 
-    it "returns the correct Date for 2019-1-1 (2019-Aug-wk1)" do
-      expect(subject.start_of_week(2019, 1, 1)).to eq Date.new(2018, 8, 5)
+      it "returns the correct Date for 2019-1-1 (2019-Aug-wk1)" do
+        expect(subject.start_of_week(2019, 1, 1)).to eq Date.new(2018, 8, 5)
+      end
     end
-  end
 
-  describe "#end_of_week" do
-    it "returns the correct date for 2017-6-1 (2017-Jan-wk1)" do
-      expect(subject.end_of_week(2017, 6, 1)).to eq Date.new(2017, 1, 7)
-    end
+    describe "#end_of_week" do
+      it "returns the correct date for 2017-6-1 (2017-Jan-wk1)" do
+        expect(subject.end_of_week(2017, 6, 1)).to eq Date.new(2017, 1, 7)
+      end
 
-    it "returns the correct Date for 2018-6-5 (2018-Jan-wk5)" do
-      expect(subject.end_of_week(2018, 6, 5)).to eq Date.new(2018, 2, 3)
-    end
+      it "returns the correct Date for 2018-6-5 (2018-Jan-wk5)" do
+        expect(subject.end_of_week(2018, 6, 5)).to eq Date.new(2018, 2, 3)
+      end
 
-    it "returns the correct Date for 2019-10-3 (2019-May-wk3)" do
-      expect(subject.end_of_week(2019, 10, 3)).to eq Date.new(2019, 5, 25)
+      it "returns the correct Date for 2019-10-3 (2019-May-wk3)" do
+        expect(subject.end_of_week(2019, 10, 3)).to eq Date.new(2019, 5, 25)
+      end
     end
-  end
 
-  describe "#start_of_month" do
-    it "returns the correct date for 2018-1 AKA 2018-Aug" do
-      expect(subject.start_of_month(2018, 1)).to eq Date.new(2017, 7, 30)
-    end
+    describe "#start_of_month" do
+      it "returns the correct date for 2018-1 AKA 2018-Aug" do
+        expect(subject.start_of_month(2018, 1)).to eq Date.new(2017, 7, 30)
+      end
 
-    it "returns the correct date for 2019-1 AKA 2019-Aug" do
-      expect(subject.start_of_month(2019, 1)).to eq Date.new(2018, 8, 5)
+      it "returns the correct date for 2019-1 AKA 2019-Aug" do
+        expect(subject.start_of_month(2019, 1)).to eq Date.new(2018, 8, 5)
+      end
     end
-  end
 
-  describe "#end_of_month" do
-    it "returns the correct date for 2018-1 AKA 2018-Aug" do
-      expect(subject.end_of_month(2018, 1)).to eq Date.new(2017, 8, 26)
-    end
+    describe "#end_of_month" do
+      it "returns the correct date for 2018-1 AKA 2018-Aug" do
+        expect(subject.end_of_month(2018, 1)).to eq Date.new(2017, 8, 26)
+      end
 
-    it "returns the correct date for 2019-1 AKA 2019-Aug" do
-      expect(subject.end_of_month(2019, 1)).to eq Date.new(2018, 9, 1)
+      it "returns the correct date for 2019-1 AKA 2019-Aug" do
+        expect(subject.end_of_month(2019, 1)).to eq Date.new(2018, 9, 1)
+      end
     end
-  end
 
-  describe "#start_of_quarter" do
-    it "returns the correct date for 2018-Q1" do
-      expect(subject.start_of_quarter(2018, 1)).to eq Date.new(2017, 7, 30)
-    end
+    describe "#start_of_quarter" do
+      it "returns the correct date for 2018-Q1" do
+        expect(subject.start_of_quarter(2018, 1)).to eq Date.new(2017, 7, 30)
+      end
 
-    it "returns the correct date for 2018-Q4" do
-      expect(subject.start_of_quarter(2018, 4)).to eq Date.new(2018, 5, 6)
-    end
+      it "returns the correct date for 2018-Q4" do
+        expect(subject.start_of_quarter(2018, 4)).to eq Date.new(2018, 5, 6)
+      end
 
-    it "returns the correct date for 2019-Q1" do
-      expect(subject.start_of_quarter(2019, 1)).to eq Date.new(2018, 8, 5)
+      it "returns the correct date for 2019-Q1" do
+        expect(subject.start_of_quarter(2019, 1)).to eq Date.new(2018, 8, 5)
+      end
     end
-  end
 
-  describe "#end_of_quarter" do
-    it "returns the correct date for 2018-Q1" do
-      expect(subject.end_of_quarter(2018, 1)).to eq Date.new(2017, 10, 28)
-    end
+    describe "#end_of_quarter" do
+      it "returns the correct date for 2018-Q1" do
+        expect(subject.end_of_quarter(2018, 1)).to eq Date.new(2017, 10, 28)
+      end
 
-    it "returns the correct date for 2018-Q4" do
-      expect(subject.end_of_quarter(2018, 4)).to eq Date.new(2018, 8, 4)
-    end
+      it "returns the correct date for 2018-Q4" do
+        expect(subject.end_of_quarter(2018, 4)).to eq Date.new(2018, 8, 4)
+      end
 
-    it "returns the correct date for 2019-Q1" do
-      expect(subject.end_of_quarter(2019, 1)).to eq Date.new(2018, 11, 3)
+      it "returns the correct date for 2019-Q1" do
+        expect(subject.end_of_quarter(2019, 1)).to eq Date.new(2018, 11, 3)
+      end
     end
-  end
 
-  describe "#start_of_year" do
-    it "returns the correct date for 2018" do
-      expect(subject.start_of_year(2018)).to eq Date.new(2017, 7, 30)
-    end
+    describe "#start_of_year" do
+      it "returns the correct date for 2018" do
+        expect(subject.start_of_year(2018)).to eq Date.new(2017, 7, 30)
+      end
 
-    it "returns the correct date for 2019" do
-      expect(subject.start_of_year(2019)).to eq Date.new(2018, 8, 5)
+      it "returns the correct date for 2019" do
+        expect(subject.start_of_year(2019)).to eq Date.new(2018, 8, 5)
+      end
     end
-  end
 
-  describe "#end_of_year" do
-    it "returns the correct date for 2017" do
-      expect(subject.end_of_year(2017)).to eq Date.new(2017, 7, 29)
-    end
+    describe "#end_of_year" do
+      it "returns the correct date for 2017" do
+        expect(subject.end_of_year(2017)).to eq Date.new(2017, 7, 29)
+      end
 
-    it "returns the correct date for 2018" do
-      expect(subject.end_of_year(2018)).to eq Date.new(2018, 8, 4)
+      it "returns the correct date for 2018" do
+        expect(subject.end_of_year(2018)).to eq Date.new(2018, 8, 4)
+      end
+
+      it "returns the correct date for 2019" do
+        expect(subject.end_of_year(2019)).to eq Date.new(2019, 8, 3)
+      end
     end
+  end
+
+  context "an alternative offset - 2 quarters after" do
+    subject { described_class.new(2) }
 
-    it "returns the correct date for 2019" do
-      expect(subject.end_of_year(2019)).to eq Date.new(2019, 8, 3)
+    it "raises a NotImplementedError - this is still TODO" do
+      expect {
+        subject
+      }.to raise_error(NotImplementedError)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: merch_calendar
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc2
+  version: 0.1.0.rc3
 platform: ruby
 authors:
 - Mitch Dempsey